# Website Shape Translator Showcase Specification

## Purpose

This specification defines the demonstration website for PortaShape's flagship capability: importing a shape, exposing the labeled values that make it up, letting a user translate or transmutate those values into a new shape, and saving the result as reusable `.posh` artifacts.

The demo uses a website because it is an immediately understandable shape. A user uploads `index.htm`, `styles.css`, and `scripts.js`; PortaShape discovers the page structure, labels, IDs, styles, scripts, assets, interactions, and reusable sections; then the user can tweak values, save the current website shape, transmutate the whole site into a new shape, or select one element such as a single `div` and turn it into a reusable component shape.

## Product framing

The website system is not a separate website builder. It is the first showcase module for PortaShape's general shape translation engine.

A **shape** is anything that has labeled things compounded into a singular labeled thing with a stable unique ID. In this module, a website shape may contain pages, sections, components, DOM nodes, text values, design tokens, assets, routes, event handlers, forms, animations, layout rules, and runtime behaviors. A selected `div` can also become a shape when PortaShape assigns or preserves a stable shape ID and records the labeled sub-values that compose it.

A **registered shape ID** allows a user or workflow to import data into that shape, export data from that shape, compare it to another shape, or translate it through a transmutation pipeline into a destination shape.

**Transmutation** is the act of changing the source shape's structure, values, semantics, or representation so it can become another shape. **Translation** is the whole movement from source shape through discovery, mapping, transmutation, verification, and destination save/export.

## Core user promise

> Upload a website, see its shape, change or transmutate it, and save the new shape so it can be reused, exported, or translated again.

## Demonstration goals

The demo must show that PortaShape can:

1. import common website files as a meaningful shape;
2. discover and label editable variables across HTML, CSS, and JavaScript;
3. register, save, load, duplicate, version, and manage website and component shape IDs;
4. present a visual data mapper over source and destination shapes;
5. support small tweaks such as changing one or two values;
6. support larger transmutations such as changing a one-page marketing site into a dashboard, landing page variant, reusable card component, or differently configured website;
7. let the user select a single DOM subtree and save it as an instantly reusable shape;
8. preview changes before committing them;
9. explain what was copied, translated, transmutated, ignored, lossy, or unresolved;
10. export the destination as website files and `.posh` artifacts.

## Inputs and upload contract

### Required upload set

The first demo version accepts exactly these files:

- `index.htm` or `index.html` — canonical page markup;
- `styles.css` — style rules, design values, layout, typography, colors, and motion definitions;
- `scripts.js` — client-side behavior, event listeners, configuration values, constants, and lightweight interactions.

### Optional later inputs

Future iterations may accept assets, fonts, images, JSON data, multiple pages, framework projects, CMS exports, design-token files, screenshots, accessibility reports, or live URLs. These should be modeled as additional adapters, not as a separate product path.

### Upload validation

The upload surface must validate:

- expected filenames and MIME/file extensions;
- maximum file size and total package size;
- parseability of HTML and CSS;
- JavaScript syntax and safe static-analysis boundaries;
- rejected executable upload behavior for the hosted demo;
- duplicate IDs and malformed DOM roots;
- missing style/script references;
- encoding and line-ending normalization.

Invalid files must produce clear validation results and preserve the user's ability to retry without losing accepted files.

## Shape discovery model

After upload, PortaShape creates a source shape record with a new stable shape ID unless the upload includes an existing `.posh` shape declaration.

Discovery should identify:

### HTML elements

- document title, meta values, landmarks, headings, sections, forms, buttons, links, images, lists, cards, tables, dialogs, and custom attributes;
- DOM paths and stable identities using existing `id`, `name`, semantic role, text signature, source location, and generated fallback IDs;
- repeated structures that may become component shapes;
- labels, accessible names, ARIA relationships, form-control associations, and successful controls;
- reusable subtrees such as `header`, `nav`, `main`, `section`, `article`, `footer`, and user-selected `div` regions.

### CSS values

- colors, fonts, spacing, sizing, border radii, shadows, breakpoints, z-index layers, animation durations/easing, grid/flex layout patterns, and CSS custom properties;
- inferred design tokens where raw values repeat or match semantic roles;
- selectors that bind style values to discovered HTML elements;
- global settings versus local component options.

### JavaScript values and behavior

- constants, configuration objects, data literals, selectors, event listeners, DOM writes, class toggles, inline state machines, fetch calls, timers, and browser API usage;
- behavior labels such as menu toggle, carousel, modal open/close, form enhancement, active search, animation trigger, or analytics event;
- ownership boundaries where plain JavaScript islands are required;
- values that can safely become controls versus behavior that must remain read-only in the demo.

### Shape variables

The UI must list discovered variables in groups:

- **Content variables** — title text, headings, paragraphs, labels, alt text, links, button copy, metadata;
- **Design variables** — color tokens, typography, spacing, layout, radii, shadows, responsive settings;
- **Structure variables** — sections, repeated cards, navigation items, forms, component boundaries;
- **Behavior variables** — toggles, event handlers, animation timings, script constants, data attributes;
- **Asset variables** — image paths, icon references, font references, downloadable files;
- **Runtime variables** — request endpoints, local UI state, browser API integrations, feature flags where detectable;
- **Policy variables** — accessibility requirements, allowed value ranges, brand constraints, security constraints.

Each variable row must show label, stable element ID, source file and location, inferred type, current value, owner/scope, confidence, editability, dependencies, and provenance evidence.

## Shape registry and dashboard

The demo needs a shape load/save/manage dashboard. It must include:

- registered shape IDs and human-readable labels;
- shape kind, such as `website`, `page`, `section`, `component`, `token-set`, `interaction`, `workflow`, or `bundle`;
- import/export capability status;
- source upload timestamp and version;
- saved variants and lineage;
- current draft versus committed versions;
- compatibility notes for translation targets;
- unresolved or lossy transformation warnings;
- quick actions: open explorer, duplicate, save as new shape, export files, export `.posh`, compare, delete local draft.

The dashboard should make the source shape, proposed shape, and destination shape visually distinct.

## Primary screens

### 1. Upload and connect screen

Purpose: import the website files and create a source shape.

Required UI:

- drag-and-drop upload zone with separate slots for `index.htm`, `styles.css`, and `scripts.js`;
- parse status for each file;
- detected references among the files;
- safety and privacy notice explaining local/hosted processing;
- `Discover shape` action;
- progressive enhancement baseline using a normal multipart form.

### 2. Shape explorer

Purpose: show the uploaded website as an inspectable system graph.

Required UI:

- live preview iframe or sandboxed preview pane;
- DOM/tree graph and searchable variable list;
- tabs for HTML, CSS, JavaScript, assets, behavior, policies, and provenance;
- hover/select synchronization between preview and variable rows;
- ability to click a DOM node or drag a bounding box in the preview to define a sub-shape;
- breadcrumbs from whole website to selected component shape;
- confidence and evidence panel for inferred labels.

### 3. Variable control surface

Purpose: let users make simple tweaks.

Required UI:

- generated controls by type: text inputs, color pickers, range sliders, select lists, token editors, code-safe toggles, and structured object editors;
- before/after value display;
- dependency warnings when one value affects multiple selectors or nodes;
- preview-only proposals until saved;
- reset, duplicate variant, and save-as-new-shape actions;
- accessibility feedback for text, contrast, labels, and focusable controls.

### 4. Visual data mapper

Purpose: map source shape elements to destination shape elements.

Required UI:

- left column for source shape elements;
- right column for destination shape template, selected existing shape, or generated blank shape;
- central relation canvas supporting direct mapping, one-to-many, many-to-one, conditional mapping, lookup, formula, template, generate, ignore, and unresolved relation types;
- suggested mappings with confidence and explanation;
- transform picker for copy, translate, transmute, derive, split, combine, tokenize, componentize, restructure, or generate;
- warnings for lossy, irreversible, permission-blocked, or unsupported mappings;
- keyboard-accessible non-canvas mapping table fallback.

### 5. Transmutation studio

Purpose: change the source shape into a new shape.

Required UI:

- target shape selector: blank website, differently configured website, reusable component, section pack, design-token set, dashboard, landing page, documentation page, or custom registered shape ID;
- transformation recipe builder with steps such as extract section, rename variables, convert CSS values to tokens, reorganize layout, split a card list into data-driven cards, change navigation structure, or wrap a subtree as a component;
- side-by-side source/proposed/destination preview;
- promptable but reviewable AI-assist area for candidate transformations, never direct unreviewed execution;
- simulation result showing changed files, generated artifacts, unresolved values, and validation results.

### 6. Save, export, and run report screen

Purpose: preserve the new shape and produce usable output.

Required UI:

- save current draft to existing shape ID or save as new registered shape ID;
- export transformed `index.htm`, `styles.css`, and `scripts.js`;
- export `.posh` bundle with systems, elements, mappings, transforms, surface, workflow, policies, snapshot, and run report;
- compare source and destination shapes;
- show provenance: upload files, discovered values, user decisions, AI suggestions if any, approvals, validation outcomes, generated outputs;
- shareable local demo summary.

## Core workflow

```text
UPLOAD FILES
  → DISCOVER WEBSITE SHAPE
  → REGISTER SOURCE SHAPE ID
  → EXPLORE VARIABLES AND SUB-SHAPES
  → CHOOSE TWEAK, COMPONENT EXTRACTION, OR TRANSMUTATION TARGET
  → MAP SOURCE VALUES TO DESTINATION VALUES
  → TRANSMUTATE STRUCTURE/VALUES
  → SIMULATE AND VERIFY
  → SAVE NEW SHAPE ID OR VERSION
  → EXPORT WEBSITE FILES AND `.posh` EVIDENCE
```

## Example scenarios

### A. Tweak one value

1. User uploads a small site.
2. PortaShape discovers a `primaryColor` variable from repeated CSS values.
3. User changes it from blue to green.
4. Preview updates.
5. User saves a new website-shape version named `campaign-site.green-variant`.
6. Export includes changed `styles.css`, a snapshot, and a run report.

### B. Transmutate a single `div` into a reusable card shape

1. User selects a product-card `div` in the preview.
2. PortaShape identifies image, title, description, price, CTA link, hover style, and click behavior.
3. User registers it as `shape.product-card.basic`.
4. User maps the card fields to a reusable component template.
5. PortaShape transmutates the raw DOM/CSS/JS into a component shape with variables and policies.
6. User exports `.posh` plus example HTML/CSS/JS for reuse.

### C. Translate a one-page site into a dashboard shape

1. User selects destination shape `dashboard.ops-basic`.
2. PortaShape maps hero statistics to metric cards, navigation to dashboard tabs, CTA links to action buttons, and sections to panels.
3. Unsupported marketing copy is marked as unresolved or moved to notes.
4. User reviews suggested relations and accepts selected transmutations.
5. Simulation produces a dashboard layout and validation report.
6. User saves destination shape `dashboard.ops-basic.from-marketing-site`.

### D. Reconfigure a website without changing its shape kind

1. User chooses destination `website` and recipe `brand refresh`.
2. PortaShape translates colors, fonts, spacing, and motion values into a new token set.
3. Structure remains mostly intact.
4. User saves the new configured website as a variant with lineage back to the source shape.

## `.posh` artifacts produced

The demo should produce a composed bundle, even when also exporting ordinary website files.

Recommended bundle contents:

- `system` — uploaded website declaration and discovered graph;
- `snapshot` — original uploaded file state and destination output state;
- `surface` — generated explorer, variable controls, mapper, and transmutation studio configuration;
- `mapping` — source-to-destination relations;
- `transform` — tweak, translation, and transmutation operations;
- `workflow` — upload, discovery, mapping, simulation, save, export steps;
- `policy` — validation rules for accessibility, security, value ranges, and shape compatibility;
- `run` — executed simulation/save/export report;
- `library` — reusable component shapes, token controls, transform recipes, and Web-Native Runtime patterns used.

The artifact must distinguish:

- source shape ID;
- selected sub-shape IDs;
- proposed shape ID;
- destination shape ID;
- saved version IDs;
- source-native paths versus semantic IDs;
- translated values versus transmutated structures;
- unresolved and intentionally ignored values.

## Web-Native Runtime implementation requirements

The demo should use the repository's Web-Native Runtime Library as a normal PortaShape toolset.

### Ownership

- Server/database or local demo backend owns saved shapes, artifacts, uploads, validation, provenance, and run records.
- URLs own selected shape, current view, selected mapper target, and saved comparison routes.
- Native controls own submitted proposals in upload, edit, mapping, and save forms.
- htmx owns upload requests, discovery jobs, variable-list filtering, preview refreshes, mapper updates, validation panels, OOB status/toast updates, and export actions.
- Alpine owns local panel state, drag hover, selected rows, disclosure state, transient preview controls, keyboard focus helpers, and unsaved local UI affordances.
- Isolated JavaScript islands own preview iframe instrumentation, visual selection overlays, graph/canvas mapping, code editor widgets, and any high-frequency rendering.
- Semantic browser events coordinate upload completion, shape selection, variable proposal, mapper relation creation, transmutation simulation completion, toast announcements, and shell close/open behavior.

### Required component patterns

- Stable Alpine shell with htmx interior for explorer panels, mapper drawers, and transmutation modals.
- htmx-replaceable components with disposable Alpine behavior for variable rows, inline edit forms, and validation cards.
- htmx-only server components for paginated variable tables and run-report fragments.
- Alpine-only local components for disclosure, tabs over already-loaded content, simple filters, and compare toggles.
- Isolated JavaScript islands for preview selection, DOM bounding boxes, source code highlighting, and relation canvas.

### Progressive enhancement

The demo must remain understandable without JavaScript:

- uploads submit through a normal form;
- discovered variables can be viewed as server-rendered tables;
- mappings can be edited with accessible forms instead of only a canvas;
- shape save/export actions are normal POST actions;
- direct URLs open saved shape, mapper, comparison, and run-report pages.

## Validation and safety

The demo must include visible validation for:

- malformed HTML/CSS/JS;
- unsafe script execution and sandbox restrictions;
- duplicate DOM IDs and inaccessible controls;
- color contrast and missing labels/alt text;
- broken asset references and links;
- unsupported JavaScript behavior;
- irreversible or lossy transmutations;
- unmapped required destination fields;
- output file generation errors;
- shape ID collisions and version conflicts.

Security constraints:

- uploaded scripts must never execute in the parent PortaShape UI;
- previews must use sandboxing and clear trust boundaries;
- generated HTML must escape untrusted text;
- AI-assisted transform suggestions must be structured, reviewed, and recorded before use;
- secrets or credentials must be references, not embedded artifacts;
- export bundles must indicate whether raw uploaded content is included.

## Data model sketch

Minimum records for the demo backend:

- `Shape` — `id`, `label`, `kind`, `status`, `createdAt`, `updatedAt`, `lineage`, `currentVersionId`;
- `ShapeVersion` — `id`, `shapeId`, `version`, `sourceFiles`, `artifactRef`, `snapshotRef`, `validationSummary`;
- `ShapeElement` — `id`, `shapeVersionId`, `label`, `kind`, `sourcePath`, `semanticPath`, `parentId`, `valueRef`, `confidence`, `evidence`;
- `ShapeVariable` — `id`, `elementId`, `label`, `type`, `scope`, `owner`, `currentValue`, `proposedValue`, `constraints`, `editable`, `dependencies`;
- `ShapeRelation` — `id`, `sourceElementId`, `destinationElementId`, `relationType`, `operation`, `transformRef`, `confidence`, `loss`, `status`;
- `TransformRecipe` — `id`, `label`, `inputShapeKinds`, `outputShapeKinds`, `steps`, `policies`, `reversibility`, `trustLevel`;
- `RunReport` — `id`, `workflowId`, `sourceShapeId`, `destinationShapeId`, `inputs`, `outputs`, `decisions`, `validation`, `warnings`, `provenance`.

## MVP boundary

The first build should support:

- upload of one three-file website package;
- server-side parsing and discovery of HTML/CSS plus conservative JavaScript static extraction;
- shape registry dashboard for local demo storage;
- variable list grouped by content/design/structure/behavior;
- live preview with selectable DOM nodes;
- saving the whole website as a shape;
- saving a selected DOM subtree as a component shape;
- editing a small set of variable types: text, links, colors, spacing, font sizes, booleans, simple script constants;
- mapping table and accessible mapper fallback;
- at least three transmutation recipes: brand refresh, component extraction, and landing-page-to-dashboard;
- export of transformed files and `.posh` bundle;
- validation/report screen with provenance.

Explicitly defer:

- arbitrary JavaScript rewriting;
- multi-page project import;
- asset pipelines beyond referenced file reporting;
- live external website crawling;
- collaborative editing;
- production credentialed deployments;
- unreviewed AI-generated transformations.

## Acceptance criteria

A successful showcase lets a user complete these tasks without developer help:

1. upload `index.htm`, `styles.css`, and `scripts.js`;
2. see the website rendered in a safe preview;
3. see a useful list of discovered variables with labels, IDs, types, and source evidence;
4. change at least one content value and one design value;
5. save the changed site as a new registered shape version;
6. select a single `div` and save it as a reusable component shape;
7. choose a destination shape and map at least five source values to it;
8. run a transmutation simulation and review warnings;
9. export transformed website files;
10. export a `.posh` bundle containing system, snapshot, surface, mapping, transform, workflow, policy, and run evidence;
11. reload the dashboard and reopen both the source and saved destination shapes.