VioTilneum Magnetic Docking for PHP pages

Welcome to the shiny purple rabbit hole. This page explains everything Kevin and ChatGPT need in order to add the draggable VioTilneum plate system to another PHP page quickly, safely, and in a fun Violet-approved way.

Jump to copy bundle

What this page is for: a reusable handoff guide. You can open this page, click one button, paste the copied content into a future chat, and I should have almost everything I need to recreate the VioTilneum feature on a different PHP page.

Violet holding a large VioTilneum plate and admiring it

Try the invention! The VioTilneum plate on this page is live. It is magnetized to a location chosen by the site administrator. 10 magnetic docks

Immediately below Violet’s introduction

Violet smiles from a violet metallic plate with a platinum message: Violet’s SI is here to help!

What is VioTilneum?

VioTilneum is a VioLabs-created alloy: remarkably strong, surprisingly flexible, gorgeous in deep-violet tones, and stable even at 100 below 0F. In the site universe, it is the perfect material for an intelligent plate that can digitally magnetize itself into place.

Remarkably strong Flexible Stable at −100°F Digitally magnetized

Below “What is VioTilneum?”

What the feature does

Places a Violet-themed VioTilneum plate on a page.
Lets the administrator drag it to other approved docking locations.
Snaps the plate neatly into place with a magnetic effect.
Saves the chosen location so everyone sees the same focus point.
Provides a dropdown fallback so the location can also be changed without dragging.

Below “What the feature does”

Files you usually need

Target PHP page where the plate appears.
Reusable include such as includes/viotilneum_plate.php.
CSS for plate layout, docking indicators, and responsiveness.
JavaScript for drag, snap, and save behavior.
Plate image asset and any supporting Violet art.
SQL for a small shared settings table.

Below “Files you usually need”

Database / auth expectations

The cleanest pattern is a tiny shared settings table, usually in the RUSSIA database, and a whitelist of valid slot names. The page should already know the logged-in username so only the admin can move the plate.

CREATE TABLE IF NOT EXISTS `RUSSIA`.`plan_ui_layout` (
  `plan_key` VARCHAR(64) NOT NULL,
  `widget_key` VARCHAR(64) NOT NULL,
  `dock_key` VARCHAR(64) NOT NULL DEFAULT 'shared',
  `updated_by_user_id` BIGINT UNSIGNED NULL,
  `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
    ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`plan_key`, `widget_key`),
  CONSTRAINT `fk_russia_ui_layout_user`
    FOREIGN KEY (`updated_by_user_id`) REFERENCES `RUSSIA`.`users`(`id`)
    ON DELETE SET NULL
);

This VioScans manual uses its own plan_key and widget_key. Moving this plate never changes the one on Cullan’s page.

Below “Database / auth expectations”

Integration checklist

Identify the target PHP page and the best docking zones.
Confirm where the login/session username comes from.
Add CSS and JavaScript assets.
Create or reuse the small settings table.
Add the include and save endpoint.
Whitelist the slot IDs and test drag/drop, dropdown change, and reset.
Verify desktop, tablet, and phone behavior.

Below the integration checklist

Best prompt ingredients for ChatGPT

When you ask me to do this again, the most helpful details are: the full server path of the target page, the domain, the auth/session method, the preferred database auth file, any admin username rules, and where you want the plate to draw attention first.

Below the ChatGPT handoff tips

Just before the copy-ready brief

Copy-ready VioTilneum integration bundle

Use the button to put the full reusable brief on your clipboard.

VioTilneum Magnetic Docking • Reuse Handoff (v2 — October 2026)
===============================================================

GOAL FOR NEXT CHAT
Install a VioTilneum nameplate on another existing PHP page. An authorized
administrator can drag it to predefined magnetic docking zones or choose a
location from a dropdown. Save one shared location in MySQL so all viewers
see the same placement. Preserve the target page's existing behavior, data,
branding, authentication, session rules, and responsive layout.

PLEASE ASK ME FOR THE CURRENT TARGET PAGE FILES
- Full filesystem path and public URL of the PHP page to modify.
- Current/live PHP source (and relevant header/footer includes, CSS, JS).
- Which authenticated username/role may move the plate.
- Existing DB credential file, schema, and table permissions.
- Whether the page is public, authenticated, or mixed-access.
- Desired default docking location and dock locations.
Do not assume VioScans and SMORTLER share session cookies. The domain's own
login determines authorization. Do not transplant the RUSSIA authentication
session to a separate domain.

LIVE WORKING REFERENCE
Page: https://vioscans.com/VioTilneum.php
Server: /var/www/vioscans.com/VioTilneum.php
Canonical plate asset: /assets/violet/docs/viotilneum_help_plate.webp
Original (if needed): violet_s_si_help_banner_original.png in deployment ZIP
Hero art: /assets/violet/docs/viotilneum_hero.png
Files used on this page:
 /includes/viotilneum_docs_engine.php  (server-side DB & secure save)
 /includes/viotilneum_docs_plate.php   (movable plate include)
 /assets/css/viotilneum-dock.css
 /assets/js/viotilneum-dock.js
 /assets/css/viotilneum-docs.css
Use these as reference implementations, NOT as drop-in assumptions for
another application. Verify site paths and auth first.

CANON & FICTION
VioTilneum is a VioLabs alloy: deep violet, flexible, remarkably
strong, stable down to -100°F. The magnetic docking is a playful on-screen
animation. Violet's character and SI badge must match the approved canon;
do not redesign her identity, badge, hair, face, or uniform.

FUNCTIONAL CONTRACT
1. One movable plate element: #vt-docs-plate or a target-specific equivalent.
2. Many whitelisted dock containers with data-vt-dock="SLOT_ID".
3. Current saved slot rendered server-side, before JS runs.
4. Admin-only drag handle and artwork dragging (mouse); touch handle only.
5. During drag, reveal all markers, use pointer events and autoscroll near
   viewport edges; find closest target; release to snap and POST save.
6. Offer a normal <select> and Reset as accessible/keyboard/mobile fallback.
7. Persist the placement with CSRF-protected same-origin POST, prepared SQL.
8. On failed save, restore the previous slot and explain the error.
9. Render plate read-only for non-admins; do not expose editing controls or CSRF.
10. Honor reduced-motion and print media; don't obstruct navigation or text.
11. This widget controls ONLY its own placement, not page content, comments,
    user accounts, or unrelated layouts.

CURRENT RUSSIA DATABASE SCHEMA (ACTUAL v5, NOT OLD layout_key SCHEMA)
CREATE TABLE IF NOT EXISTS `RUSSIA`.`plan_ui_layout` (
  `plan_key` VARCHAR(64) NOT NULL,
  `widget_key` VARCHAR(64) NOT NULL,
  `dock_key` VARCHAR(64) NOT NULL DEFAULT 'shared',
  `updated_by_user_id` BIGINT UNSIGNED NULL DEFAULT NULL,
  `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
    ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`plan_key`, `widget_key`),
  KEY `idx_ui_layout_user` (`updated_by_user_id`),
  CONSTRAINT `fk_russia_ui_layout_user`
    FOREIGN KEY (`updated_by_user_id`) REFERENCES `RUSSIA`.`users` (`id`)
    ON DELETE SET NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;

IMPORTANT: Each application/widget needs a distinct (plan_key, widget_key),
so its plate does not move another app's plate. Existing Russia family app
has a separate key. The VioScans docs page uses:
  plan_key='vioscans_viotilneum_manual'
  widget_key='help_plate'
  default dock='hero-after'
The docs page uses the VioScans session: $_SESSION['username']==='crothersk'
to authorize editing. It connects to MySQL using
/var/outsidePDR/CROTHERS_auth.php variables $servername, $username,
$password, and explicitly sets the database name to RUSSIA.
The docs page stores updated_by_user_id=NULL because that login is not a
RUSSIA.users authentication session. Another app should record a user id
only if the identity comes from that app's verified authentication system.

SECURE SAVE ENDPOINT
- POST only, JSON {"action":"plate_position","value":"ALLOWED_SLOT"}.
- Include X-CSRF-Token from a server-generated session token.
- Check authenticated user and permission on the server (not only UI).
- Validate the slot against a strict PHP whitelist.
- Use PDO, prepared statements, exceptions, utf8mb4, no interpolated user SQL.
- Upsert only the intended (plan_key, widget_key) row.
- Return {"ok":true,"slot":"..."}; on error JSON with appropriate HTTP code.
- Cache-Control no-store for save and sensitive session pages.
- Never expose DB credentials or raw exception text to visitors.

POSITIONING & CSS
- Magnetic markers are normally hidden; reveal them on drag.
- Occupied marker contains the plate; unoccupied markers take no space.
- Create stable docking containers near meaningful chapter or content
  boundaries, not over text or interactive inputs.
- Keep plate responsive, max-width constrained, aspect ratio intact.
- On narrow screens stack content vertically; touch dragging starts from
  small handle so the image doesn't block ordinary page scrolling.
- Read-only visitors see the persisted position. Fallback for DB errors is
  a safe default slot (with logged error, not exposure of credentials).

TO REUSE ON ANOTHER PAGE
Provide me the PHP page and existing dependencies, and ask me to adapt the
reference implementation above. In the new site, update include and asset
paths, the DB schema/key, authentication source, allowed docks, CSS, and
POST handler. Use the same official VioTilneum/SI artwork if desired.
Deliver a root-ready ZIP with PHP, CSS, JS, images, any idempotent SQL, and
installation + rollback commands. Test PHP syntax, JS parsing, copy button,
drag/drop, select/reset, save failure rollback, narrow screens, and guest mode.

REQUEST TEMPLATE
"Add the VioTilneum magnetic docking system to:
  SERVER FILE: [ACTUAL PHP FILE PATH]
  PUBLIC URL: [URL]
  LOGIN/ADMIN RULE: [USERNAME OR ROLE]
  DATABASE: [SCHEMA + CREDENTIAL FILE]
  DESIRED DOCKS: [LIST]
Keep the existing app intact. Use the architecture in this pasted brief.
I'll attach the current file(s). Return a root-ready ZIP and deploy steps."

END OF REUSABLE VioTilneum HANDOFF.

At the bottom of the page