@stacksjs/defaults 0.75.361 → 0.75.366

package/ai/skills/stacks-technical-diagrams/renderers/workflow/workflow-migration-geometry.mjs

@@ -1,5 +1,17 @@
 const TARGET_SCHEMA_VERSION = 2;
 
+// Planning removes absolute route assertions, but must keep the same rank
+// policy as the document whose coordinates will be mapped into that plan.
+// An authored canvas likewise keeps its established plan: draft-only optional
+// corridor growth must not consume space that a valid fixed canvas lacks.
+const absoluteGeometryPolicy = Symbol('workflow absolute geometry policy');
+export function preservesWorkflowAbsoluteGeometry(workflow) {
+  return workflow[absoluteGeometryPolicy] ?? (Array.isArray(workflow.meta?.viewBox) || (workflow.edges || []).some((edge) => (
+    Array.isArray(edge.via) || Array.isArray(edge.labelAt)
+    || edge.channelX !== undefined || edge.channelY !== undefined
+  )));
+}
+
 function clone(value) {
   return JSON.parse(JSON.stringify(value));
 }
@@ -12,6 +24,7 @@ function clone(value) {
 export function intrinsicWorkflow(workflow) {
   const intrinsic = clone(workflow);
   intrinsic.schema_version = TARGET_SCHEMA_VERSION;
+  intrinsic[absoluteGeometryPolicy] = preservesWorkflowAbsoluteGeometry(workflow);
   intrinsic.meta = { ...intrinsic.meta };
   delete intrinsic.meta.viewBox;
   return intrinsic;
@@ -40,6 +53,10 @@ export function planningWorkflow(workflow) {
     return [automatic];
   });
 
+  // Full-topology contracts cannot be checked against a layout-only subgraph.
+  // The source and final mapped candidate retain and validate these contracts.
+  if (planned.edges.length !== workflow.edges.length) delete planned.semanticChecks;
+
   if (Array.isArray(planned.mainPath)) {
     const projectedPairs = new Set(planned.edges.map((edge) => `${edge.from}\u0000${edge.to}`));
     const projectionBreaksMainPath = planned.mainPath.some((from, index) => (

package/ai/skills/stacks-technical-diagrams/renderers/workflow/workflow-placement-repair.mjs

@@ -0,0 +1,94 @@
+// One optional placement proposal for a failed readable workflow.
+// Never applied to the authored input; the compiler verifies the complete result.
+export function proposeWorkflowPlacement(input) {
+  if (input.schema_version !== 2 || input.meta?.viewBox
+    || input.groups?.length || input.phases?.length
+    || !input.mainPath?.length || input.nodes.length > 64
+    || input.edges.some(e => ['via', 'channelX', 'channelY', 'labelAt'].some(k => e[k] !== undefined))) {
+    return { eligible: false, reason: 'Needs unpinned v2, complete mainPath, no authored regions, <=64 nodes.' };
+  }
+  const main = input.mainPath;
+  const mainIndex = new Map(main.map((id, i) => [id, i]));
+  const nodes = new Map(input.nodes.map(n => [n.id, n]));
+  const laneIndex = new Map(input.lanes.map((l, i) => [l.id, i]));
+  if (main.some(id => !nodes.has(id)) || new Set(main).size !== main.length)
+    return { eligible: false, reason: 'Invalid mainPath.' };
+  const out = new Map(input.nodes.map(n => [n.id, input.edges.filter(e => e.from === n.id).map(e => e.to)]));
+  function reachable(id) {
+    const found = new Set(), todo = [...out.get(id)];
+    while (todo.length) {
+      const next = todo.pop();
+      if (found.has(next) || !nodes.has(next)) continue;
+      found.add(next); todo.push(...out.get(next));
+    }
+    return found;
+  }
+  const reach = new Map(input.nodes.map(n => [n.id, reachable(n.id)]));
+  const offMain = input.nodes.filter(n => !mainIndex.has(n.id));
+  const offIds = new Set(offMain.map(n => n.id));
+  const components = [], assigned = new Set();
+  for (const n of offMain) {
+    if (assigned.has(n.id)) continue;
+    const component = [], todo = [n.id];
+    while (todo.length) {
+      const id = todo.pop();
+      if (assigned.has(id)) continue;
+      assigned.add(id); component.push(id);
+      for (const e of input.edges) {
+        if (e.from === id && offIds.has(e.to)) todo.push(e.to);
+        if (e.to === id && offIds.has(e.from)) todo.push(e.from);
+      }
+    }
+    const cyclic = component.some(id => main.some(m => reach.get(id).has(m) && reach.get(m).has(id)));
+    components.push({ ids: component, cyclic });
+  }
+  const leftRail = components.some(c => c.cyclic);
+  if (!leftRail) return { eligible: false, reason: 'No return cycle connected to the main path.' };
+  const rightRail = components.some(c => !c.cyclic && c.ids.length > 1);
+  const start = leftRail ? 1 : 0, end = rightRail ? 4 : 5;
+  const proposed = structuredClone(input), moved = new Map(proposed.nodes.map(n => [n.id, n]));
+  let col = start;
+  for (let i = 0; i < main.length; i++) {
+    const current = moved.get(main[i]), previous = moved.get(main[i - 1]);
+    if (previous && laneIndex.get(current.lane) <= laneIndex.get(previous.lane)) col = Math.min(col + 1, end);
+    current.col = col;
+  }
+  for (const component of components) {
+    for (const id of component.ids) {
+      const n = moved.get(id);
+      const parents = input.edges.filter(e => e.to === id && mainIndex.has(e.from)).map(e => moved.get(e.from));
+      n.col = component.cyclic ? 0 : component.ids.length > 1 ? 5
+        : Math.min(end, Math.max(start, ...parents.map(p => p.col + 1)));
+      // Place same-lane failure branches below their main-path source row.
+      if (component.cyclic && parents.some(p => p.lane === n.lane)) {
+        const sameLane = main.map(m => moved.get(m)).filter(m => m.lane === n.lane);
+        n.yOffset = Math.max(...sameLane.map(m => (m.yOffset || 0) + (m.height || 52) / 2)) + (n.height || 52) / 2 + 40;
+      }
+    }
+  }
+  const groups = new Map();
+  for (const n of proposed.nodes) {
+    const key = n.lane + ':' + n.col;
+    groups.set(key, [...groups.get(key) || [], n]);
+  }
+  function order(n) {
+    if (mainIndex.has(n.id)) return mainIndex.get(n.id);
+    const incoming = input.edges.filter(e => e.to === n.id && mainIndex.has(e.from)).map(e => mainIndex.get(e.from));
+    return incoming.length ? Math.min(...incoming) + 0.5 : main.length;
+  }
+  for (const group of groups.values()) {
+    if (group.length < 2) continue;
+    group.sort((a, b) => order(a) - order(b) || a.id.localeCompare(b.id));
+    const total = group.reduce((sum, n) => sum + (n.height || 52), 0) + 40 * (group.length - 1);
+    let top = -total / 2;
+    for (const n of group) {
+      n.yOffset = top + (n.height || 52) / 2;
+      top += (n.height || 52) + 40;
+    }
+  }
+  const changes = [];
+  for (let i = 0; i < input.nodes.length; i++) for (const field of ['col', 'yOffset']) {
+    if (input.nodes[i][field] !== proposed.nodes[i][field]) changes.push({op: field in input.nodes[i] ? 'replace' : 'add', path: `/nodes/${i}/${field}`, value: proposed.nodes[i][field]});
+  }
+  return {eligible: true, proposed, changes, components, rails: {left: leftRail, right: rightRail}};
+}

package/ai/skills/stacks-technical-diagrams/schemas/README.md

@@ -1,4 +1,4 @@
-# Technical Diagram JSON IR Schemas
+# Archify JSON IR Schemas
 
 Each typed renderer consumes a JSON intermediate representation (IR) validated
 against one of the schemas in this folder before any layout work happens.
@@ -10,37 +10,54 @@ against one of the schemas in this folder before any layout work happens.
 | `workflow.schema.json` | `diagram_type: "workflow"` | `lanes`, `phases`, `groups`, `mainPath`, `nodes`, `edges` |
 | `sequence.schema.json` | `diagram_type: "sequence"` | `participants`, `segments`, `messages`, `activations` |
 | `dataflow.schema.json` | `diagram_type: "dataflow"` | `stages`, `nodes`, `flows` |
-| `lifecycle.schema.json` | `diagram_type: "lifecycle"` | `lanes`, `states`, `transitions` |
+| `lifecycle.schema.json` | `diagram_type: "lifecycle"` | `mainPath`, `states`, `transitions` |
 | `architecture.schema.json` | `diagram_type: "architecture"` | `components`, `boundaries`, `connections` |
-| `common.schema.json` | shared `$defs` only (no top-level document) | - |
+| `erd.schema.json` | `diagram_type: "erd"` | `entities`, `relationships` |
+| `tree.schema.json` | `diagram_type: "tree"` | `nodes` (each with one `parent`) |
+| `class.schema.json` | `diagram_type: "class"` | `types`, `relationships` |
+| `timeline.schema.json` | `diagram_type: "timeline"` | `events` (`lanes` optional) |
+| `waterfall.schema.json` | `diagram_type: "waterfall"` | `spans` (each with optional `parent`) |
+| `common.schema.json` | shared `$defs` only (no top-level document) | — |
 
 Every diagram schema requires `schema_version`, `diagram_type`, `meta` (with
-`title`), and its structural arrays - except `segments`, `activations`, and
-`cards`, which are optional - and sets `additionalProperties: false` at every
+`title` and a durable portable `output`), and its structural arrays — except `segments`, `activations`, ERD and class
+`relationships`, and `cards`, which are optional — and sets `additionalProperties: false` at every
 level, so unknown fields are rejected rather than silently ignored.
 
 Every `meta` object also accepts `animation: "trace"` for opt-in SVG/CSS motion
 in generated HTML. Omit it, or set `"none"`, for the default static output.
-It also accepts `locale: "en" | "zh-CN"`. The field selects the fixed Viewer
-UI, renderer-owned default legend and accessibility copy, document-title
-suffix, and `<html lang>` value; it does not translate authored strings.
-Omitting it preserves legacy behavior and resolves to English. Unsupported
-locale values fail schema validation instead of being guessed or silently
-rewritten.
+It also accepts `locale`, any well-formed language tag (schema pattern
+`^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$`). The field selects the fixed Viewer UI,
+renderer-owned default legend and accessibility copy, document-title suffix,
+and `<html lang>` value; it does not translate authored strings. The bundled
+catalogs enrolled in `locales/manifest.json` (`en`, `zh-CN`, `zh-TW`, `es`, `ko`, `ar`) are
+selected by tag, case-insensitively; region and script variants are distinct
+tags. Any other tag needs a matching `translations` object (see below) or the
+renderer falls back to English and discloses it.
+Omitting `locale` preserves legacy behavior and resolves to English.
+Malformed locale tags fail schema validation instead of being guessed or
+silently rewritten.
+
+`meta.translations` is an optional per-key override, as data: an object mapping
+canonical message keys (`locales/en.json`) to translated strings whose
+`{placeholder}` tokens match the English source. Each message resolves as:
+valid `translations` value → bundled catalog for `locale` → English. An
+unrecognized key or mismatched placeholders never replaces a valid
+lower-priority message and fails no render; `validate`/`render`/`deliver`
+report rejected entries and the final resolved coverage to stderr.
 `visual_preset` accepts `classic` (the stable default), `signal-flow` (luminous
 motion-forward presentation), `blueprint` (high-contrast engineering review),
 or `editorial` (warm publication-style design review and documentation).
 Presets change only viewer styling; they do not alter semantic IDs or geometry.
-Sequence `meta` additionally accepts `column_fit`. The default `fixed` keeps
-the historical 108px column gap and 86px participant boxes, so an authored
-diagram renders at the same coordinates no matter how wide its viewBox is.
-`spread` derives the gap and box width from the viewBox instead, which turns a
+Sequence `meta` additionally accepts `column_fit`. The default `spread` applies whether or not `meta.viewBox` is supplied.
+Explicit `fixed` keeps the historical 108px column gap and 86px participant
+boxes. `spread` derives column distance and box width from the viewBox, with
+at least a 16px gutter between participant cards, which turns a
 wide canvas into column distance and label room rather than empty space on the
 right. Lane order, IDs, and message semantics are unchanged either way.
 
-It may also include up to five guided `views`. Each view has a unique `id`, a
-reader-facing `label`, a non-empty `focus` list of existing semantic node IDs,
-and an optional short `note`.
+`meta.views` is retired. The schemas still accept the old guided-view shape so
+existing files keep validating, but renderers ignore it; do not author it.
 
 ### Legend presentation contract
 
@@ -63,7 +80,7 @@ Architecture documents that omit an explicit `viewBox` size that automatic
 viewBox from the same measured resolved legend footprint used for final SVG
 layout. Across all renderers, legacy documents that omit `meta.legend` use a
 compatibility-safe implicit `auto`: if the resolved legend cannot fit an
-explicit authored viewBox without overlap, the renderer omits the complete legend
+explicit authored viewBox without overlap, Archify omits the complete legend
 instead of turning a previously valid schema-v1 document into a hard failure.
 Once an author adds `meta.legend` (including explicit `mode: "auto"`), the
 layout is intentional and unfit labels or bands fail with a path-prefixed
@@ -82,6 +99,8 @@ Supported keys are renderer-owned:
 | Sequence | `emphasis`, `return`, `security`, `dashed`, `default` |
 | Dataflow | `emphasis`, `security`, `dashed`, `database`, `default` |
 | Lifecycle | `start`, `active`, `waiting`, `decision`, `success`, `failure`, `neutral`, `external` |
+| ERD | `pk`, `fk`, `uk`, `one`, `many`, `optional` |
+| Class | `dependency`, `association`, `inheritance`, `realization`, `composition`, `aggregation` |
 
 Labels are presentation only: they do not rename the stable kind, change
 nodes/relationships, or create Semantic Lens edge facts. Sequence message and
@@ -99,8 +118,8 @@ local to the current page.
 
 Every semantic node collection (`components`, `nodes`, `participants`, and
 `states`) also accepts one optional `brand`: either a canonical string returned
-by `.claude/skills/stacks-technical-diagrams/bin/diagrams brands --json`, or a digest-pinned `{ "url", "sha256" }` object
-returned by `.claude/skills/stacks-technical-diagrams/bin/diagrams brands capture <url> --json`. Known IDs and known-brand
+by `archify brands --json`, or a digest-pinned `{ "url", "sha256" }` object
+returned by `archify brands capture <url> --json`. Known IDs and known-brand
 domains use the bundled vector catalogue. Unknown URLs must be captured in that
 explicit command before authoring; render and validate never perform an
 unpinned network capture. Unsafe, unavailable, changed, or unsupported content
@@ -111,8 +130,15 @@ output.
 
 Workflow supports schema versions 1 and 2. Version 1 remains the fixed-layout
 compatibility contract; version 2 opts into the readable workflow compiler and
-can be produced explicitly with `.claude/skills/stacks-technical-diagrams/bin/diagrams migrate workflow ... --to-schema 2`.
-The other four diagram schemas keep `schema_version` pinned to `1`.
+can be produced explicitly with `archify migrate workflow ... --to-schema 2`.
+Lifecycle accepts only version 3, an automatic main-path layout (see the
+[lifecycle renderer](../renderers/lifecycle/README.md)).
+The other three diagram schemas keep `schema_version` pinned to `1`; they have
+no schema-version migration command. For any of the five diagram types, repair
+a legacy missing or nonportable `meta.output` in the source and run `validate`.
+For a workflow v1-to-v2 migration specifically, `migrate workflow` also accepts
+`--output reports/diagram.html` to put that portable value in the separate v2
+destination without changing the legacy source.
 
 Workflow also accepts optional `semanticChecks`. `allowedRoots` and
 `allowedTerminals` close the set of intentional graph sources and sinks;
@@ -124,7 +150,13 @@ workflow behavior and including a satisfied contract does not change SVG or
 layout-receipt bytes.
 
 A file that validates today must keep validating and rendering within its
-declared version throughout the 2.x release line. Additive viewer,
+declared version throughout the 2.x release line. The explicitly reviewed
+portable-output hardening is the one exception: older v1 documents that omit
+`meta.output` must add a portable POSIX-relative `.html` path (for example,
+`reports/diagram.html`); ordinary explicit CLI output arguments do not replace
+this durable authored value. The workflow-only v1-to-v2 migration command may
+instead receive that value explicitly as `--output reports/diagram.html`; it
+writes the value only to its separate validated destination. Additive viewer,
 accessibility, and presentation improvements may enhance generated HTML, but
 they must not reinterpret authored IR or turn a previously valid profile-less
 v1 file into a new hard layout failure. Breaking IR changes require a new
@@ -134,22 +166,33 @@ version; additive, backwards-compatible fields do not.
 
 The five diagram schemas reference `common.schema.json#/$defs/...`:
 
-- `id` - element identifiers, pattern `^[a-zA-Z][a-zA-Z0-9_-]*$`
-- `point` - an `[x, y]` pair of numbers (used by `via` and `labelAt`)
-- `componentType` - `frontend`, `backend`, `database`, `cloud`, `security`,
+- `id` — element identifiers, pattern `^[a-zA-Z][a-zA-Z0-9_-]*$`
+- `point` — an `[x, y]` pair of numbers (used by `via` and `labelAt`)
+- `componentType` — `frontend`, `backend`, `database`, `cloud`, `security`,
   `messagebus`, `external`
-- `locale` - the bounded renderer locale, `en` or `zh-CN`
-- `brandMark` - one optional built-in brand ID or explicit HTTP(S) site URL
-- `variant` - `default`, `emphasis`, `security`, `dashed` (sequence messages
+- `locale` — a well-formed renderer locale tag (bundled catalogs are listed in
+  `locales/manifest.json`; any other tag needs a matching `translations` object)
+- `translations` — canonical message key → translated string, layered over the
+  bundled catalog for `locale`, then English
+- `portableOutputPath` — the portable POSIX-relative `.html` path used by
+  `meta.output`; see the two output-path boundaries in the
+  [delivery contract](../references/delivery-contract.md#output-path-contracts)
+- `brandMark` — one optional built-in brand ID or explicit HTTP(S) site URL
+- `variant` — `default`, `emphasis`, `security`, `dashed` (sequence messages
   extend this list locally with `return`)
-- `legendMode` and `legendEntry` - the shared strict mode and label/visibility
+- `legendMode` and `legendEntry` — the shared strict mode and label/visibility
   override shapes used by each renderer-owned key map
-- `guidedViews` - the bounded, read-only reader paths accepted by `meta.views`
-- `cards` - the summary-card blocks rendered below the SVG
+- `guidedViews` — the retired `meta.views` shape, still accepted and ignored
+- `cards` — the summary-card blocks rendered below the SVG
 
 Lifecycle state `type` is mode-specific (`start`/`active`/`waiting`/...) and
 stays in `lifecycle.schema.json`.
 
+The JSON Schema definition is the portable contract's structurally expressible
+preflight. The shipped generated validator wrapper and CLI additionally enforce
+byte-based component limits and the complete runtime path contract; consumers
+that need the same cross-platform acceptance boundary should use that wrapper.
+
 ## Runtime validation
 
 At development time, `scripts/generate-validators.mjs` compiles all five
@@ -163,10 +206,14 @@ express cleanly here: duplicate view IDs, duplicate focus IDs, focus IDs that do
 not exist in the diagram's semantic collection, and duplicate authored
 relationship IDs within the mode's relationship collection.
 
-Architecture additionally supports opt-in, revision-pinned repository evidence.
-`meta.repository` names a public GitHub URL and full commit SHA; a component may
-carry one to three `sources` with repo-relative POSIX paths, optional line
-ranges, and optional labels. Shape is schema-checked, then the renderer requires
+All five modes support opt-in, revision-pinned repository evidence.
+`meta.repository` names the repository URL and full commit SHA, with optional
+`provider` (`github`, `gitee`, or `gitlab`) and `link_mode` (`web` or `local-only`; see the
+authoring contract); a node may carry one to three `sources` with repo-relative POSIX paths, optional line
+ranges, and optional labels. Sources are authored on the mode's own node
+collection — Architecture `components`, Workflow and Data Flow `nodes`,
+Sequence `participants`, Lifecycle `states` — and the verified payload is keyed
+by node id. Shape is schema-checked, then the renderer requires
 `--repo-root`: the local Git origin must match, and Git must prove the commit,
 blobs, and requested lines. Verified evidence is embedded outside the canonical
 SVG for the Semantic Passport and Node Finder; ordinary documents and visual
@@ -176,7 +223,7 @@ exports carry no repository evidence.
 
 `meta.quality_profile` and `meta.engineering_profile` answer different
 questions. `quality_profile` is available in all five modes and controls how
-strictly the renderer judges composition. `engineering_profile` is an optional
+strictly Archify judges composition. `engineering_profile` is an optional
 Architecture-only semantic contract; omitting it preserves the ordinary v1
 behavior.
 
@@ -199,8 +246,8 @@ validators drift from their schemas.
 ## Error format
 
 Schema violations exit non-zero. Each ajv error is reported on its own line as
-the instance path - annotated with the nearest enclosing element's `id` or
-`label` - followed by the message and parameters:
+the instance path — annotated with the nearest enclosing element's `id` or
+`label` — followed by the message and parameters:
 
 ```text
 workflow schema validation failed:

package/ai/skills/stacks-technical-diagrams/schemas/architecture.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/tt-a1i/archify/schemas/architecture.schema.json",
-  "title": "Technical Architecture Diagram",
+  "title": "Archify Architecture Diagram",
   "type": "object",
   "additionalProperties": false,
   "required": ["schema_version", "diagram_type", "meta", "components"],
@@ -11,30 +11,18 @@
     "meta": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["title"],
+      "required": ["title", "output"],
       "properties": {
         "title": { "type": "string", "minLength": 1 },
         "locale": { "$ref": "common.schema.json#/$defs/locale" },
+        "translations": { "$ref": "common.schema.json#/$defs/translations" },
         "subtitle": { "type": "string" },
-        "output": { "type": "string" },
+        "output": { "$ref": "common.schema.json#/$defs/portableOutputPath" },
         "animation": { "$ref": "common.schema.json#/$defs/animation" },
         "visual_preset": { "$ref": "common.schema.json#/$defs/visualPreset" },
         "quality_profile": { "$ref": "common.schema.json#/$defs/qualityProfile" },
         "engineering_profile": { "enum": ["deployment-ownership"] },
-        "repository": {
-          "type": "object",
-          "additionalProperties": false,
-          "required": ["url", "revision"],
-          "properties": {
-            "url": {
-              "type": "string",
-              "minLength": 1
-            },
-            "provider": { "enum": ["github", "gitee"] },
-            "link_mode": { "enum": ["web", "local-only"] },
-            "revision": { "type": "string", "pattern": "^[a-fA-F0-9]{40}$" }
-          }
-        },
+        "repository": { "$ref": "common.schema.json#/$defs/repository" },
         "views": { "$ref": "common.schema.json#/$defs/guidedViews" },
         "legend": {
           "type": "object",
@@ -95,23 +83,9 @@
           "label": { "type": "string", "minLength": 1 },
           "sublabel": { "type": "string" },
           "tag": { "type": "string" },
+          "icon": { "$ref": "common.schema.json#/$defs/nodeIcon" },
           "brand": { "$ref": "common.schema.json#/$defs/brandMark" },
-          "sources": {
-            "type": "array",
-            "minItems": 1,
-            "maxItems": 3,
-            "items": {
-              "type": "object",
-              "additionalProperties": false,
-              "required": ["path"],
-              "properties": {
-                "path": { "type": "string", "minLength": 1, "maxLength": 240 },
-                "line": { "type": "integer", "minimum": 1 },
-                "end_line": { "type": "integer", "minimum": 1 },
-                "label": { "type": "string", "minLength": 1, "maxLength": 48 }
-              }
-            }
-          },
+          "sources": { "$ref": "common.schema.json#/$defs/sourceReferences" },
           "row": { "type": "integer", "minimum": 0 },
           "col": { "type": "integer", "minimum": 0 },
           "pos": { "$ref": "common.schema.json#/$defs/point" },