Add Paper Figure Studio and OpticalSetup bridge ports

.github/workflows/pages.yml

@@ -1,4 +1,4 @@
-name: Deploy prototype to GitHub Pages
+name: Deploy PicSetup to GitHub Pages
 
 on:
   push:
@@ -28,11 +28,13 @@ jobs:
       - name: Configure Pages
         uses: actions/configure-pages@v5
 
-      - name: Stage static site
+      - name: Stage PicSetup app
         run: |
-          mkdir _site
-          cp prototype/index.html prototype/robots.txt _site/
-          cp -R prototype/assets _site/assets
+          mkdir -p _site/src _site/integrations/opticalsetup
+          cp app/index.html app/styles.css app/icon.svg app/manifest.webmanifest app/sw.js _site/
+          cp app/src/*.js _site/src/
+          cp app/integrations/opticalsetup/receiver-adapter.js _site/integrations/opticalsetup/
+          cp prototype/robots.txt _site/robots.txt
 
       - name: Upload static site
         uses: actions/upload-pages-artifact@v3

.github/workflows/validate.yml

@@ -0,0 +1,34 @@
+name: Validate successor candidate
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Validate application
+        run: npm run app:validate
+
+      - name: Ensure generated build stays untracked
+        run: test -z "$(git status --short -- app/dist)"

.gitignore

@@ -1,3 +1,4 @@
 .DS_Store
 node_modules/
 prototype/node_modules/
+app/dist/

ACCEPTANCE_TESTS.md

@@ -0,0 +1,71 @@
+# Acceptance tests
+
+## Automated gate
+
+From the repository root:
+
+```sh
+npm run app:validate
+```
+
+The gate must:
+
+1. parse every `app/src/*.js` runtime module and the OpticalSetup receiver adapter;
+2. pass the complete Node regression suite with no failures;
+3. build `app/dist/PicSetup-Lab-10x-preview.html`;
+4. leave generated `app/dist/` output untracked.
+
+The existing prototype remains independently checkable:
+
+```sh
+npm run prototype:test
+npm run prototype:check
+```
+
+The `prototype/` tree object must be identical to the base commit.
+
+## Required model and graph cases
+
+The automated suite must cover:
+
+- lossless coherent-network conservation and finite residuals;
+- Mach–Zehnder and resonator response over declared sweeps;
+- physical and schematic route-length contracts;
+- hierarchy collapse/expand response preservation;
+- deterministic tuning, tolerance, and pulse fixtures;
+- semantic, SAX, gdsfactory, and S-parameter workflows;
+- typed-domain compatibility and exclusion of non-optical links from the coherent solve;
+- the hybrid paper template's component vocabulary and optical/electrical/RF/control graph;
+- `setup-port/1` encoding, URL, manifest, and receiver round trips;
+- explicit unresolved spatial state at the OpticalSetup boundary.
+
+## Browser acceptance journey
+
+Serve `app/` over HTTP and verify in a current browser:
+
+1. The application loads without runtime errors.
+2. A user can create, connect, move, inspect, save, and reopen a photonic circuit.
+3. Wavelength or phase changes produce complementary MZI output behavior.
+4. Unsupported or disconnected state produces an explicit warning rather than a fabricated result.
+5. Paper Figure Studio opens the included hybrid template.
+6. The template contains a chip figure, OpticalSetup boundaries, RF/electrical/control wiring, instrumentation, plot, image placeholder, panel label, and operating-condition annotation.
+7. Component label placement, metadata visibility, connection labels, offsets, and arrow direction are editable.
+8. SVG export is content cropped and opens as a valid vector document.
+9. PNG export has a white or transparent background as selected and a publication-scale resolution.
+10. Bridge JSON and the bridge manifest identify `setup-port/1`, units, both power references, omissions, source identity, and target URL.
+11. Opening a bridge retains `incomingBridge` and `bridgeSchema=setup-port/1` in the OpticalSetup URL.
+12. No action implies that the external OpticalSetup receiver is already deployed.
+
+## Pull-request acceptance
+
+Before review:
+
+- CI is green on the proposed commit.
+- The diff is confined to the successor application, governing contracts, documentation, scripts, and validation workflow.
+- `prototype/` is unchanged.
+- No generated `dist/`, dependency directory, credential, or machine-specific `/mnt/data` path is committed.
+- The PR description separates implemented behavior from manual browser evidence, external receiver work, merge, and deployment.
+
+## Production acceptance
+
+Merge does not by itself authorize replacement of the public prototype. A production release requires explicit approval, a scoped deployment plan, a live URL/version check, browser smoke on the deployed artifact, and a recorded rollback path.

CLAIMS_AND_VALIDATION.md

@@ -0,0 +1,51 @@
+# Claims and validation
+
+## Candidate status
+
+The application under `app/` is a greenfield successor candidate. The current public site continues to use the immutable `prototype/` snapshot unless a separately authorized release replaces it.
+
+## Supported claims
+
+Subject to the automated checks and the declared model contract, the candidate may be described as:
+
+- a browser-based semantic PIC and publication-figure workbench;
+- an interactive reduced-order coherent scattering-network simulator;
+- a typed hybrid figure editor whose non-optical domains remain outside the optical solve;
+- a Paper Figure Studio with content-cropped SVG and high-resolution PNG export;
+- a sender and neutral receiver-adapter proposal for the versioned `setup-port/1` OpticalSetup boundary;
+- a dependency-light local application that can produce a standalone HTML build.
+
+The included component models are analytical, imported, pedagogical, or reduced order as their definitions state. Output is suitable for topology exploration, system-level reasoning, teaching, and figure composition within those assumptions.
+
+## Prohibited claims
+
+Without additional primary validation, the candidate must not be described as:
+
+- fabrication ready, mask-layout ready, DRC clean, or foundry qualified;
+- a calibrated predictor of device, thermal, electrical, RF, control, biological, behavioral, operational, or performance outcomes;
+- a full-vector, multimode, polarization-resolved, nonlinear, or full-wave electromagnetic solver;
+- proof that imported S-parameters are passive, causal, correctly referenced, or process valid;
+- a deployed OpticalSetup receiver, live synchronization layer, or coupled PicSetup/OpticalSetup solver;
+- the current production site merely because local tests or a standalone build pass.
+
+## Validation matrix
+
+| Boundary | Evidence | What it establishes | What it does not establish |
+| --- | --- | --- | --- |
+| JavaScript syntax | `npm run app:check` | Runtime and receiver modules parse in Node | Browser behavior or model correctness |
+| Model and interface regression | `npm run app:test` | Declared invariants, exports, typed-domain isolation, template, and bridge round trips | Full browser interaction or external receiver integration |
+| Standalone packaging | `npm run app:build` | Multi-file source can be bundled into one local HTML artifact | Public deployment |
+| Browser smoke | Serve `app/` and exercise the acceptance journey | Current browser loads and primary UI/export actions work | Cross-browser completeness or production acceptance |
+| Prototype preservation | Compare the `prototype/` tree against the base commit | Prior-art snapshot was not modified | Production availability |
+| Pull-request CI | GitHub Actions validation on the proposed commit | Clean-run reproducibility in the hosted runner | Merge, release, DNS, or live-site replacement |
+| Live verification | Inspect the deployed URL and release identity after an authorized deployment | Public artifact and selected smoke behavior are live | Scientific calibration or user acceptance |
+
+## Export claims
+
+Semantic JSON preserves the hybrid graph and bridge manifest. SAX YAML and gdsfactory Python are topology scaffolds restricted to physical optical content; they are not PDK-qualified layouts or substitutes for foundry compact models.
+
+SVG/PNG output is publication-oriented composition. A stylized plot panel is diagram content unless replaced by exported numerical data. Image panels preserve user-supplied imagery but do not validate its provenance or quantitative meaning.
+
+## Reporting results
+
+Validation reports must give exact pass/fail counts, record warnings, and identify skipped manual or external checks. Tests, browser smoke, deployment, OpticalSetup receiver adoption, and public acceptance are separate completion boundaries.

DEPLOYMENT_AUTHORIZATION.md

@@ -0,0 +1,5 @@
+# Deployment authorization
+
+On 2026-07-28, the repository owner authorized merging pull request #2 and replacing the GitHub Pages deployment artifact with the greenfield PicSetup app under `app/`.
+
+The immutable `prototype/` snapshot remains preserved in the repository and is no longer the Pages publication source after this change.

INTERFACE_CONTRACT.md

@@ -0,0 +1,66 @@
+# Interface contract
+
+## Internal semantic graph
+
+The saved PicSetup document is the source of truth for circuit topology, figure composition, component parameters, units, model versions, and provenance.
+
+Components expose typed ports. Connections declare one of:
+
+- `optical`
+- `electrical`
+- `rf`
+- `control`
+- `annotation`
+
+The editor must reject incompatible port/domain combinations. Semantic JSON preserves the complete hybrid graph. SAX- and gdsfactory-oriented handoffs include only physical optical topology and must state that figure-only objects and non-optical links were omitted.
+
+## OpticalSetup bridge: `setup-port/1`
+
+The first cross-setup interface is a deterministic, versioned document handoff between a PicSetup optical boundary and OpticalSetup.
+
+Every payload contains:
+
+- `schema`: exactly `setup-port/1`;
+- a stable bridge ID;
+- source application, document, component ID, and component name;
+- target application and URL;
+- `domain`: exactly `optical`;
+- interface kind and direction;
+- a declared reference frame and orientation;
+- wavelength in nanometres;
+- PicSetup-side and OpticalSetup-side power in milliwatts;
+- an explicit power reference and coupling efficiency;
+- polarization, guided-mode label, boundary phase, and CW/pulsed timing;
+- supported capabilities and explicit omissions;
+- an optional return URL;
+- a creation timestamp.
+
+Allowed directions are `input`, `output`, and `bidirectional`. Supported interface kinds distinguish fiber mode, chip-edge mode, grating/free-space mode, and free-space beam boundaries.
+
+The sender encodes JSON as base64url and opens the target with:
+
+```text
+?incomingBridge=<payload>&bridgeSchema=setup-port/1
+```
+
+Base64url is transport encoding, not encryption, authentication, or authorization. Bridge payloads must not contain secrets.
+
+## Power and state boundary
+
+The payload carries both interface-side powers and the coupling efficiency so the reference is inspectable. The receiver must not silently reinterpret one side's power as the other.
+
+PicSetup exports a scalar guided-mode boundary. It does not invent or transfer beam waist, numerical aperture, sampled transverse field, wavefront, or laboratory coordinates. Those properties remain unresolved until OpticalSetup supplies them.
+
+Phase is a declared boundary value in radians. CW/pulsed state includes repetition rate in megahertz and pulse duration in picoseconds only when pulsed. `createdAt` records document handoff time; it is not a shared simulation clock.
+
+## Receiver and ownership
+
+`app/integrations/opticalsetup/receiver-adapter.js` validates and normalizes the payload into a neutral boundary descriptor. It deliberately stops before scene creation.
+
+OpticalSetup must map that descriptor into its own component and scene APIs, choose unresolved spatial state, and review/deploy the receiver in Luca Genchi's repository. PicSetup must not copy OpticalSetup private state or claim receiver deployment based on the sender adapter.
+
+The initial interface is not live synchronization, co-simulation, or a distributed multi-physics solve. Stable bridge identity and a return URL allow later workflows without implying real-time authority.
+
+## Evolution
+
+Incompatible changes require a new schema identifier. Receivers must reject unsupported schema or domain values rather than guessing. Optional extensions must preserve the meaning and units of existing fields and keep unknown state explicit.

PHOTONICS_MODEL_CONTRACT.md

@@ -0,0 +1,77 @@
+# Photonics model contract
+
+## Status and ownership
+
+This contract governs the greenfield candidate under `app/`. It does not describe or modify the immutable production snapshot under `prototype/`.
+
+PicSetup owns guided photonic topology and reduced-order circuit behavior. OpticalSetup owns free-space optical geometry and propagation. ElectricalSetup owns electrical drive and readout dynamics. A typed boundary may exchange declared state between those domains; it does not transfer model ownership.
+
+## State and governing equation
+
+Each modeled optical port carries an incoming complex amplitude `a` and outgoing complex amplitude `b`. Amplitudes are power normalized, so `|a|²` and `|b|²` are optical powers in milliwatts.
+
+Every compact component contributes a wavelength-dependent scattering relation:
+
+```text
+b = S a + s
+```
+
+Waveguide connections contribute the propagation operator `C`. The complete connected optical network is solved simultaneously:
+
+```text
+(I - S C) b = s
+```
+
+The reported linear-system residual and the optical power budget are separate diagnostics. A small algebraic residual is not evidence of a physically complete loss model.
+
+## Units and conventions
+
+- Vacuum wavelength is expressed in nanometres.
+- Geometric and optical path lengths are expressed in micrometres.
+- Optical powers are expressed in milliwatts.
+- Phase values in solver state are radians. Display controls may expose degrees when labeled.
+- A port represents one declared scalar guided mode, TE0-like by default.
+- Component port reference planes are the component connection points represented in the semantic graph.
+- Connection direction and component port roles determine the sign and source/sink interpretation; visual arrow direction alone has no solver authority.
+
+Physical routing numerically integrates the rendered path to obtain geometric length. Schematic routing uses the connection's explicit optical length. The interface must identify which mode is active.
+
+## Solver admission
+
+Only connections whose declared domain is `optical` and whose ports are optically compatible enter `C`.
+
+`electrical`, `rf`, `control`, and `annotation` connections remain part of the semantic document and publication figure, but they do not enter the coherent optical solve. Diagram-only objects never acquire a compact optical model merely because they are visually connected.
+
+The modeled registry includes analytical or imported reduced-order components such as sources, couplers, splitters, phase and amplitude elements, resonators, filters, detectors, crossings, terminations, grating/edge interfaces, delay lines, imported S-parameter blocks, and reducible passive hierarchy. Each definition must declare its ports, parameters, active-model scope, provenance, assumptions, and rendering metadata.
+
+## Power accounting
+
+The solver reports launched, detected, terminated, component-loss, waveguide-loss, and unaccounted power where the selected models expose enough state. Conservation tests use passive, lossless fixtures with declared matched boundaries. Lossy or incomplete circuits must not be described as conservative merely because the numerical residual is small.
+
+## Validity domain
+
+The candidate is an interactive compact-model workbench. It is not:
+
+- a cross-section or full-chip Maxwell solver;
+- a fabrication-ready mask-layout or DRC tool;
+- a calibrated foundry model library;
+- a polarization-resolved or multimode solver unless an imported model explicitly supplies those channels;
+- a nonlinear, thermal-crosstalk, RF, SPICE, PCB, control-system, or full-wave time-domain simulator;
+- proof of passivity, causality, reference-plane correctness, or fabrication validity for user-imported S-parameters.
+
+Pulse analysis reconstructs a linear response from sampled frequency-domain compact models. Detector bandwidth may shape the electrical pulse readout but does not alter the CW optical network.
+
+## Required validation
+
+Changes to the model layer must retain:
+
+- finite complex amplitudes and bounded numerical residuals for supported connected fixtures;
+- lossless passive power conservation within the tolerance recorded in the test;
+- complementary Mach–Zehnder outputs under wavelength or phase variation;
+- physical/schematic route-length semantics;
+- hierarchy collapse/expand response preservation;
+- deterministic seeded tolerance results;
+- isolation of non-optical connection domains from the coherent solve;
+- explicit warnings for invalid, disconnected, unsupported, or numerically problematic states.
+
+Passing these checks validates the declared reduced-order behavior only. It does not establish fabrication accuracy, live deployment, or public acceptance.

README.md

@@ -5,7 +5,7 @@
 - **Live prototype:** https://picsetup.com/
 - **Prototype release verified:** 2026-07-26 (`20260726T002235Z-478235af2650`); check the URL for current availability
 - **Field:** Integrated photonics
-- **Status:** Greenfield planning wrapper with a preserved prototype snapshot
+- **Status:** Greenfield successor candidate with a preserved production prototype
 
 ## Vision
 
@@ -23,7 +23,26 @@ PicSetup is part of the **Setup Universe**: independently deployed scientific an
 
 Read [AGENTS.md](./AGENTS.md) before planning or implementing work.
 
-The present browser demo should not constrain the next architecture. Before substantial implementation, this repository expects `VISION.md`, `PHOTONICS_MODEL_CONTRACT.md`, `INTERFACE_CONTRACT.md`, `CLAIMS_AND_VALIDATION.md`, and `ACCEPTANCE_TESTS.md`.
+The present browser demo should not constrain the next architecture. The candidate successor is governed by `VISION.md`, `PHOTONICS_MODEL_CONTRACT.md`, `INTERFACE_CONTRACT.md`, `CLAIMS_AND_VALIDATION.md`, and `ACCEPTANCE_TESTS.md`.
+
+## Successor candidate
+
+`app/` contains the dependency-light greenfield workbench candidate. It combines an editable semantic PIC canvas, compact coherent-network analysis, typed cross-domain figure connections, publication SVG/PNG export, and versioned OpticalSetup bridge ports.
+
+Paper Figure Studio can combine simulated photonic objects with diagram-only instruments, RF/electrical/control wiring, plots, image panels, annotations, and chip boundaries without admitting non-optical links into the coherent solve. Its included hybrid template demonstrates the complete figure workflow.
+
+The `setup-port/1` bridge is a deterministic document handoff. PicSetup emits an explicit scalar guided-mode boundary; OpticalSetup retains authority over free-space geometry, beam waist, numerical aperture, wavefront, and receiver-side scene construction. The neutral receiver adapter under `app/integrations/opticalsetup/` is a focused integration proposal, not a deployment to Luca Genchi's repository.
+
+To validate or serve the candidate locally:
+
+```sh
+npm run app:validate
+npm run app:serve
+```
+
+Then open http://127.0.0.1:4174/.
+
+The candidate is not deployed by the current Pages workflow. Acceptance, merge, and replacement of the live prototype remain separate decisions.
 
 ## Prototype model boundary
 
@@ -52,7 +71,7 @@ npm run prototype:serve
 
 Then open http://127.0.0.1:4173/?setup=pic.
 
-These commands validate only the legacy prototype. This wrapper intentionally has no future-product test suite until the greenfield implementation begins.
+These commands validate only the legacy prototype. The successor has its own tests and build under `app/`; neither suite demonstrates a production deployment.
 
 ## Setup Universe
 

app/.gitignore

@@ -0,0 +1,3 @@
+.DS_Store
+*.log
+dist/