yugoo-design 0.1.2 → 0.2.0

package/payload/shared/authoring/studio-creators/source/packages/skills-web-app/bundles/page_design/reference/artifact-contract.md

@@ -0,0 +1,164 @@
+# Page output contract
+
+For canvas generation or revision, read [the canvas guide](canvas-guide.md).
+It supplements the existing methods and output contract; it applies to both
+new design and reconstruction without replacing domain-specific rules.
+
+Shared by authoring and reconstruction; this defines representation, not which Pages or design to invent. The installed schema/validation remain authoritative.
+
+## Installed resource addressing
+
+This contract and the validator are installed Bundle resources, not project
+WorkingCopy files. DSH binds `read_skill_resource` to this Bundle: read
+`reference/artifact-contract.md` without a `page_design/` prefix. It binds
+`run_skill_script` below the installed `scripts/` directory: use
+`path:"page-design.mjs"`, not `scripts/page-design.mjs`. The script's
+`input_file` and `input_files` are Design-Files-relative project artifacts.
+An empty project `list`/`glob` for scripts or references does not mean the
+validator is unavailable. Invoke the actual tool; a failure is a diagnostic,
+not permission to invent bindings or omit required file validation.
+
+## Files and shared inputs
+
+Canonical state is `page_design/page_design.json`. Preserve stable Page/connection IDs, full orders, valid upstream references and user-authored canvas positions/sections. The panel renders the map directly from JSON.
+
+`common_spec.source: "design_style"` means the actual saved Style result. Read its JSON and landed tokens before artifact work. The spec contains shared layout description, Logo, ordered navigation with existing Page targets and semantic icon references, and component/pattern decisions; not HTML or a second stylesheet. `logo.mark_ref` resolves to Style's SVG `brand.mark_id`; for raster Logo omit it and use `brand.logo_image.path`. Each navigation `icon_ref` resolves to `config.icons`. `uses_shared_layout: false` preserves a surface with its own layout; menu membership, page hierarchy and shell membership are distinct. Match actual source surfaces during reconstruction, not an invented universal shell.
+
+Connections store `id`, `source_page_id`, `target_page_id`, `label` (not `trigger`). Each `function_ref` and `evidence_ref` must resolve to the same semantic capability, not just an existing ID.
+
+A connection may carry `preview_context`, a flat string map of selection
+metadata, for example `{"selection":"garden"}`. It is not a copy of the
+selected entity's facts, a URL, a routing expression or persisted form state.
+Use at most 16 keys, ASCII identifier keys matching
+`[A-Za-z][A-Za-z0-9_-]{0,63}`, string values of at most 256 UTF-16 code units,
+and at most 4096 UTF-8 bytes for the sorted-key JSON object. Reject
+`__proto__`, `constructor` and `prototype`; nested objects, arrays and other
+value types are invalid. Omission preserves existing context-free navigation.
+Different source hotspots may use separate stable connections to the same
+target Page, with distinct selection values; do not add a Page per sample.
+
+On a runtime supporting this contract, the Host resolves context from the
+current canonical connection and injects a single reserved
+`<script type="application/json" id="dsh-design-preview-context">` into the
+target preview. Never author that element or send context in frame messages.
+Target artifact code may read the block's `textContent` and `JSON.parse` it to
+select already-present synthetic/accepted content. Use DOM text operations,
+not `innerHTML`, URL routing, storage, network requests or executable string
+interpolation. Without a block (including manual Page selection), show an
+honest default or a request to select an item, never an unrelated item's
+details. Unknown selections must show a clear unavailable state. Returning,
+manual selection or a source revision/reader change clears inbound context.
+This is preview selection, not application persistence or a business-data
+model. Older installed runtimes without this capability remain a disclosed
+limitation; source declarations alone do not upgrade them.
+
+File validation checks context shape/budgets and reserved-element ownership;
+it does not prove that the target JavaScript uses the selection correctly.
+Actually click each materially distinct source choice, inspect the target's
+identity and return path, then repeat the affected route after a revision.
+
+Bind each artifact through `design_delegate` or serial `design_focus_artifact`: kind `page_html`, ID = stable Page ID, file = exact Page path. Supply current Page descriptor, common_spec, incoming/outgoing connections, focused evidence, token map and Style asset authority to a Worker.
+
+For forward-design synthesis and the bounded Worker brief, use
+[task-to-page-method.md](task-to-page-method.md). Keep evidence locators and
+material conditions with excerpts; exact assets and validator inputs remain
+file-backed. Do not require every Worker to reread complete upstream files.
+
+## Map file check
+
+Before delegating or serially generating HTML, run `page-design.mjs` with
+`args: ["validate-map-file"]`, `input_file: "page_design/page_design.json"`
+and `input_files: ["design_style/design_style.json"]`. The script reads the
+exact saved `config` including SVG bytes; never copy or summarize Style into
+`input_context`. This checks map references without
+HTML generation. If an icon or brand reference is missing, fix a wrong Page
+reference using a semantically correct existing asset, or report the precise
+Style gap to the main Agent. Do not invent SVG authority or send every Worker
+into the same missing-asset failure. Rerun after shared references change.
+
+
+## HTML and preview bindings
+
+Each Page is a complete standalone HTML document at `page_design/pages/<page-id>.html`; no HTML in JSON, nested page shell, fragments or generated page-map SVG. Use local assets. The panel supplies the landed `design_style/tokens.css`; consume its existing `--ds-*` names, never declare a competing namespace or reference unknown tokens. Original raster brand/images use plain `img src` paths relative to the HTML (PNG/JPEG/WebP); SVG icons use the exact Style authority. Unsupported assets/presentation remain a reported limitation.
+
+- Cross-page controls use `data-prototype-page="<target-page-id>"`.
+- Meaningful interactive elements have unique `data-prototype-id` and readable `data-prototype-label`.
+- Mark every outgoing connection exactly once with `data-prototype-connection="<connection-id>"`; do not mark incoming connections.
+- The validator returns `bindings` for canonical `source_element_id` and `source_element_label`; do not invent bindings before HTML exists.
+- No remote dependency, navigation URL or cross-page routing script. Optional `data-design-icon` / `data-design-brand` markers resolve to current Style IDs; they are not fidelity tests.
+
+## Validate and integrate each file
+
+For every serial or delegated Page artifact, call `run_skill_script` with
+`path: "page-design.mjs"`, `args: ["validate-html-file"]`, `input_file`
+equal to its exact pre-bound HTML path, `input_context: {"page_id":"<page-id>"}`,
+and `input_files` containing exactly these authoritative paths:
+
+```json
+["page_design/page_design.json", "design_style/design_style.json", "design_style/tokens.css"]
+```
+
+The Host reads those files directly; the script derives state, assets and token
+names from their bytes. Do not send copied `state`, `style_authority`, SVG or
+`authoritative_tokens` objects. File mode never falls back to those objects when
+a required file is missing. Workers use this same call: script inputs are
+read-only; their only writable file remains their assigned HTML artifact.
+The Host passes the file bytes directly to the script; never read and resend
+the complete HTML through model tool arguments. Repair the same file on a
+non-zero result. On success, use the returned `bindings` and update the
+matching canonical state. Validate every new or changed Page this way,
+persist each successful Page immediately in the current files without an
+intermediate Git publication, then run `design_validate` and close through
+`design_publish({action:"complete"})` once. Do not assemble every Page HTML
+into a publication payload.
+
+The checks establish mechanical integrity, not source fidelity. If shared source-based Style is missing or wrong, report that exact owning-Bundle issue to the main Agent; do not change Style files or invent a Page-private replacement.
+
+## Native CLI equivalent (Codex, Claude Code, Qoder)
+
+When the host uses native shell instead of `run_skill_script`, use the same
+installed script, not a recreated validator. ROOT is the exact Design Files
+directory returned by the host; SCRIPT is this Bundle's installed script path.
+
+```sh
+node "$SCRIPT" validate-map-file --design-files "$ROOT" --input-file page_design/page_design.json
+node "$SCRIPT" validate-html-file --design-files "$ROOT" --input-file page_design/pages/home.html --page-id home
+```
+
+Replace the example `home` with the assigned stable Page ID and artifact path.
+The CLI reads the same fixed authority files, rejects escaping paths/symlinks,
+and writes nothing. Both modes return diagnostics and compact bindings on stdout.
+The old stdin context envelope remains supported for already-loaded callers;
+new work uses file-backed inputs. No inline fallback occurs in file mode.
+
+## Failure and recovery
+
+- Exit 2 / `kind: input_error`: fix the call or missing/malformed input file.
+  Do not interpret missing transport context as a missing design decision.
+- Exit 1 / `valid: false`: the supplied files fail mechanical validation.
+  Repair the named Page defect; a true missing Style asset goes to its owner.
+- Exit 0: mechanical validation passed, not proof of visual/interaction quality.
+
+At resume, inspect accepted refs and existing files at planned stable paths.
+Validate existing HTML against current file inputs before regenerating it. If
+it passes, restore/integrate its artifact ref and returned bindings through the
+executor's canonical JSON tools; the script never writes JSON. An existing file
+alone is not acceptance. Preserve valid siblings, repair only failed pages, and
+recheck affected artifacts if the shared map or Style changes before publication.
+Do not race map/Style edits with a Worker frontier. Repeated identical diagnostics
+without progress must be reported, not retried indefinitely or bypassed by
+deleting required connections. Cancellation is not permission to start fallback
+work; resume only on a later authorized request. Report unfinished pages honestly.
+
+## Independent-page frontier
+
+For two or more independent pages and an available `design_delegate_frontier`,
+submit `{batch_id, items}` once. Each item must include `artifact_kind: "page_html"`,
+`artifact_id`, exact `artifact_file`, and a complete bounded `prompt` pointing to
+this contract and the required file-input paths. A batch ID is an idempotency key,
+not a stored task list: never call the tool with only `batch_id`. Reuse it only
+with the identical ordered items. Use `design_delegate` for one page or when the
+frontier tool is unavailable; native hosts use their documented subagent adapter.
+Integrate every successful receipt, then address failed/not-started pages within
+the remaining budget. Neither a receipt nor a normal Worker exit substitutes for
+the Producer's file validation and canonical integration.

package/payload/shared/authoring/studio-creators/source/packages/skills-web-app/bundles/page_design/reference/canvas-guide.md

@@ -0,0 +1,45 @@
+# Page navigation canvas
+
+Shared representation entry. Read [the Page output contract](artifact-contract.md)
+for map/artifact authority, preview contexts, file validators and failure handling.
+For new design read [task-to-page-method.md](task-to-page-method.md) as directed by
+the existing SKILL. Reconstruction preserves observed organization rather than
+running forward task synthesis or choosing a new aesthetic.
+
+## Facts, nodes and connections
+
+`page_design/page_design.json` owns Page IDs, orders, entry Pages, hierarchy,
+connections and accepted HTML refs. One node is one Page; a directional edge is
+a meaningful jump with a source-owned trigger label. Hierarchy, navigation menu
+membership and shared-shell membership are different and do not imply jumps.
+Generated Page HTML remains a file-backed artifact, not a second map/SVG.
+
+## Groups, positions, routing and labels
+
+The current `navigation_workspace` binds pages, connections and canvas sections.
+Preserve user-authored `canvas_position` and section membership/geometry; these
+are explicit layout data, not executable product facts. Initial maps let the
+installed renderer lay out nodes rather than inventing coordinate fields.
+The renderer owns ports/routing/measurement; do not replace its navigation
+grammar with AI model/knowledge bands. Names/trigger labels must be legible and
+identify the actual Page/jump. Viewport, zoom and selection remain local UI.
+
+## Unknowns, interaction and saving
+
+Missing accepted HTML is planned/unavailable, not a completed Page. Missing
+upstream evidence is reported; do not invent function or Style IDs. Canvas and
+form use the same map/save path. A layout-only save changes no Page behavior;
+a connection/semantic revision checks the smallest affected artifact set, as
+specified in the existing contract. Already-persisted diffs are not replayed.
+Keep accepted unrelated artifacts and exact style/source pins. Preview context
+selects existing content; it is not routing, persistence or duplicated entity facts.
+
+## Existing examples and verification
+
+Use the SKILL's minimal state and existing contract's preview-context example,
+not another preview authority. Run actual map/HTML checks and reject escaping or
+missing artifacts and invalid bindings. Visually trace a principal route and
+any materially different selection to its real destination/context; inspect
+resize/labels/narrow scrolling and return behavior. Separate map validation,
+actual click-through, durable save/reopen and installed-host support. A valid
+hotspot marker or screenshot alone proves neither navigation nor persistence.

package/payload/shared/authoring/studio-creators/source/packages/skills-web-app/bundles/page_design/reference/task-to-page-method.md

@@ -0,0 +1,82 @@
+# From user tasks to a coherent page system
+
+This method uses the existing Page map fields. It adds no schema, mandatory
+story record, separate planning artifact or extra user gate. Examples below
+illustrate reasoning, not facts to copy into a project.
+
+## Synthesize before assigning pages
+
+Start with what the user wants to accomplish in a concrete situation. For each
+material task, identify its starting context, the object being worked on,
+relevant state and permissions, action, observable outcome and continuation.
+Use answered questions and current instructions for intent; functions for
+capabilities; flows for sequence; objects for identity/context; rules and roles
+for conditions. Read relevant records, not every Bundle by default. A KAG query
+can locate uncertain relationships or change impacts; verify its source records.
+Missing evidence stays an explicit assumption or a consequential user question.
+
+Group work that shares context and supports one coherent task. Distinguish:
+- Global destinations: stable, recurrent places users deliberately return to.
+- Contextual pages: object detail or workspaces entered from a selected context.
+- Views and actions: tabs, filters, dialogs or steps within an existing surface.
+
+A capability name, database entity or flow step does not automatically earn a
+page or a global menu item. Conversely, a long-lived task may warrant its own
+workspace. Decide from task continuity, frequency, retained context and scope;
+there is no fixed page/menu count or universally preferred hierarchy.
+
+For example, an expense product might put recurring work under an expense list,
+with review/export actions on a selected report. A dedicated auditor queue can
+still be justified by a separate recurring task. Neither 'export is always a
+page' nor 'export must never be a page' follows from the function name.
+
+## Persist the decisions in existing fields
+
+- `purpose`: explain the primary task and intended outcome in its context,
+  rather than copying the function description or listing feature IDs.
+- `audience`, `key_content`, `key_actions`: express priority, necessary context,
+  task progression and important conditional behavior. Secondary actions need
+  not compete with the primary task as equally prominent cards.
+- `function_refs`, `evidence_refs`: cite actual source records. Distinguish a
+  relevant constraint from an instruction to display all fields of that record.
+- `parent_id`, `entry_page_ids`, `connections`: express organization, entry and
+  meaningful transitions respectively. Connection labels can describe the
+  carried context and outcome; hierarchy alone does not imply a jump.
+- `common_spec.layout`, `navigation`, `shared_components`: capture the settled
+  cross-page organization, actual global destinations and repeated patterns.
+  Style supplies visual language; product navigation comes from task synthesis.
+
+Trace representative tasks across the proposed map before the existing map
+handoff. Check lost object context, duplicated responsibilities, dead ends,
+feature-only menu entries and rules promoted to permanent UI clutter. Explain
+the principal route and any material tradeoff briefly to the user. Preserve
+confirmed structure on continuation; a newly discovered shared conflict goes
+back to the executor, not into a Worker's private redesign.
+
+## Page Worker brief
+
+Use an ordinary task prompt, with these contents as needed:
+1. Exact Page ID/path, primary task, starting condition and expected result.
+2. Settled shared layout/navigation and relevant Style decisions; concrete
+   token/asset locators for exact source reads, not copied validator payloads.
+3. Relevant neighboring pages and incoming/outgoing transitions, including
+   object context. Full unrelated page descriptions are unnecessary.
+4. Relevant source excerpts with file and record/pointer locators, indicating
+   checkpoint or current working-copy basis; assumptions clearly identified.
+5. What this page owns, what it must preserve, and the file-backed validation
+   contract. Include KAG pins only if actually supplied by the query result.
+
+The Worker uses supplied evidence, reads gaps or exact assets as needed, and
+implements the task with clear emphasis. It may improve local arrangement but
+does not change shared navigation, business policy or sibling responsibilities.
+Source contradictions and missing shared decisions are reported for integration.
+
+## Review the integrated result
+
+Mechanical checks validate files and bindings. The executor separately checks
+that a user can recognize their task, identify the primary action, retain the
+right object/state across pages and reach the outcome. Inspect the relevant
+preview/content for this review; receipts and CSS token consistency alone are
+insufficient. Check material alternate conditions without displaying every
+exception permanently. Repair only affected pages. Report browser behavior as
+unverified if only static inspection was possible.

package/payload/shared/authoring/studio-creators/source/packages/skills-web-app/bundles/page_design/schema.yaml

@@ -0,0 +1,118 @@
+# page_design Design Files data contract (write-time validation).
+# Faithful declarative translation of extend-design-skill
+# skills/page_design/schema.py (Pydantic, extra="forbid"), extended with
+# evidence_refs under DSH schema_version 7.
+#
+# Disk-as-truth: each page's generated HTML lives on disk at
+# design_files/page_design/pages/{page-id}.html. Canonical Page records carry
+# durable artifact refs only; Host execution events drive queued/running/failed
+# activity in the panel.
+type: object
+additional_properties: false   # PageDesignState extra="forbid"
+properties:
+  skill_name: { knowledge: { role: metadata }, type: string }
+  schema_version: { knowledge: { role: metadata }, type: enum, values: [7] }   # constant 7
+  stage: { type: enum, values: [mapped, generating, completed, needs_revision] }
+  pages:
+    type: map
+    value:
+      type: object
+      additional_properties: false   # PageNode extra="forbid"
+      required: [id, name, purpose]
+      properties:
+        id: { type: string }          # must equal the mapping key
+        name: { type: string }
+        purpose: { type: string }
+        uses_shared_layout: { type: boolean } # omitted in legacy files means true; false uses page-specific layout
+        parent_id: { type: string, nullable: true, knowledge: { role: reference, target: '#/pages' } }
+        page_type: { type: enum, values: [overview, list, detail, form, workspace, content, other] }  # default other
+        audience: { type: array, items: { type: string } }
+        key_content: { type: array, items: { type: string } }
+        key_actions: { type: array, items: { type: string } }
+        function_refs: { type: array, items: { type: string, knowledge: { role: reference, target: 'function_modules/function_modules.json#/functions' } } }
+        evidence_refs: { type: array, items: { type: string, knowledge: { role: reference } } } # stable skill:id evidence references
+        style_pattern_refs: { type: array, items: { type: string, knowledge: { role: reference, target: 'design_style/design_style.json#/config/component_patterns' } } }
+        canvas_position:
+          type: object
+          nullable: true
+          additional_properties: false   # CanvasPosition extra="forbid"
+          properties:
+            x: { type: number }
+            y: { type: number }
+        artifact_file: { type: string, nullable: true }
+  page_order: { knowledge: { role: metadata }, type: array, items: { type: string } }
+  entry_page_ids: { type: array, items: { type: string, knowledge: { role: reference, target: '#/pages' } } }
+  connections:
+    type: map
+    value:
+      type: object
+      additional_properties: false   # PageConnection extra="forbid"
+      required: [id, source_page_id, target_page_id]
+      properties:
+        id: { type: string }               # must equal the mapping key
+        source_page_id: { type: string, knowledge: { role: reference, target: '#/pages' } }
+        target_page_id: { type: string, knowledge: { role: reference, target: '#/pages' } }
+        label: { type: string }
+        source_element_id: { type: string }      # data-prototype-id hotspot binding
+        source_element_label: { type: string }
+        preview_context:
+          knowledge: { role: metadata }
+          type: map
+          value: { type: string }
+  connection_order: { knowledge: { role: metadata }, type: array, items: { type: string } }
+  canvas_sections:
+    type: map
+    value:
+      type: object
+      additional_properties: false
+      required: [id, label, page_ids, canvas_position, canvas_size]
+      properties:
+        id: { type: string }
+        label: { type: string }
+        page_ids: { type: array, items: { type: string, knowledge: { role: reference, target: '#/pages' } } }
+        canvas_position:
+          type: object
+          additional_properties: false
+          required: [x, y]
+          properties:
+            x: { type: number }
+            y: { type: number }
+        canvas_size:
+          type: object
+          additional_properties: false
+          required: [width, height]
+          properties:
+            width: { type: number }
+            height: { type: number }
+  common_spec:
+    type: object
+    nullable: true
+    additional_properties: false
+    required: [layout, logo, navigation, shared_components]
+    properties:
+      layout: { type: string }
+      logo:
+        type: object
+        additional_properties: false
+        required: [description]
+        properties:
+          name: { type: string }
+          description: { type: string }
+          mark_ref: { type: string }
+      navigation:
+        type: array
+        items:
+          type: object
+          additional_properties: false
+          required: [id, label]
+          properties:
+            id: { type: string }
+            label: { type: string }
+            target_page_id: { type: string, knowledge: { role: reference, target: '#/pages' } }
+            group: { type: string }
+            icon_ref: { type: string, knowledge: { role: reference, target: 'design_style/design_style.json#/config/icons' } }
+      shared_components: { type: array, items: { type: string } }
+      visual_pattern_refs: { type: array, items: { type: string, knowledge: { role: reference, target: 'design_style/design_style.json#/config/component_patterns' } } }
+      source: { type: enum, values: [design_style] }
+  style_theme: { type: string }
+  style_epoch: { knowledge: { role: metadata }, type: number }

package/payload/shared/authoring/studio-creators/source/packages/skills-web-app/bundles/page_design/validation.yaml

@@ -0,0 +1,104 @@
+# page_design validation contract.
+# Host-enforced declarative validation for the DSH schema_version 7 Page map.
+# HTML, hotspot, and token checks belong to the foreground
+# Producer and the Bundle's ordinary scripts/page-design.mjs tool.
+skill: page_design
+
+rules:
+  - id: referenced_files_present
+    scope: [state]
+    code: page_design.referenced_artifact_invalid
+    check:
+      referenced_files: ["pages.*.artifact_file"]
+
+  - id: empty_map
+    scope: [state]
+    code: page_design.empty_map
+    message: "The page map has no pages."
+    repair_hint: "Propose at least one page before confirming the map."
+    check: { non_empty_map: pages }
+
+  - id: empty_order
+    scope: [state]
+    code: page_design.empty_order
+    message: "page_order is empty, so the map cannot render."
+    repair_hint: "List every active page id in page_order."
+    check: { non_empty_list: page_order }
+
+  - id: order_covers_pages
+    scope: [state]
+    code: page_design.order_covers_pages
+    message: "page_order must contain every page exactly once."
+    repair_hint: "Send the complete page_order whenever pages change; order replaces rather than appends."
+    check: { order_exactly_covers_map: { order: page_order, map: pages } }
+
+  - id: page_key_matches_id
+    scope: [state]
+    code: page_design.page_key_mismatch
+    message: "A pages mapping key differs from its page id."
+    repair_hint: "Keep every mapping key equal to the page id; a rename never justifies a new id."
+    check: { map_keys_match_field: { map: pages, field: id } }
+
+  - id: empty_page_name
+    scope: [state]
+    code: page_design.empty_page_name
+    message: "Page {pid} has an empty name."
+    repair_hint: "Give the page a short user-facing name."
+    check:
+      for_each_in_order: { order: page_order, map: pages }
+      non_empty_string: name
+
+  - id: empty_page_purpose
+    scope: [state]
+    code: page_design.empty_page_purpose
+    message: "Page {pid} has an empty purpose."
+    repair_hint: "State the one primary user task this page helps complete."
+    check:
+      for_each_in_order: { order: page_order, map: pages }
+      non_empty_string: purpose
+
+  - id: function_refs_unique
+    scope: [state]
+    code: page_design.function_refs_duplicate
+    message: "Page {pid} function_refs contains duplicates."
+    repair_hint: "A function may appear on multiple pages, but only once per page."
+    check: { map_entries_have_unique_string_list: { map: pages, field: function_refs } }
+
+  - id: entry_refs_page
+    scope: [state]
+    code: page_design.entry_refs_page
+    message: "entry_page_ids references unknown page {pid}."
+    repair_hint: "Entry pages must exist in the map; keep at least one entry."
+    check: { order_refs_map: { order: entry_page_ids, map: pages } }
+
+  - id: connection_order_covers
+    scope: [state]
+    code: page_design.connection_order_covers
+    message: "connection_order must contain every connection exactly once."
+    repair_hint: "Send the complete connection_order whenever connections change."
+    check: { order_exactly_covers_map: { order: connection_order, map: connections } }
+
+  - id: connection_key_matches_id
+    scope: [state]
+    code: page_design.connection_key_mismatch
+    message: "A connections mapping key differs from its connection id."
+    repair_hint: "Keep every mapping key equal to the connection id."
+    check: { map_keys_match_field: { map: connections, field: id } }
+
+  - id: connection_source_exists
+    scope: [state]
+    code: page_design.connection_source_missing
+    message: "Connection {pid} source_page_id references an unknown page."
+    repair_hint: "Connections must connect existing pages; hierarchy alone never creates a connection."
+    check:
+      for_each_in_order: { order: connection_order, map: connections }
+      member_of_map: { value: source_page_id, map: pages }
+
+  - id: connection_target_exists
+    scope: [state]
+    code: page_design.connection_target_missing
+    message: "Connection {pid} target_page_id references an unknown page."
+    repair_hint: "Connections must connect existing pages."
+    check:
+      for_each_in_order: { order: connection_order, map: connections }
+      member_of_map: { value: target_page_id, map: pages }