@ankhorage/devtools 1.10.10 → 1.10.12

package/dist/tools/skills/assets/zora-designer/references/workflow.md

@@ -1,137 +1,95 @@
-# Design, Composition, and Template Workflow
-
-Use this workflow for `interactive`, `screen`, `screens`, and `template`. Audit uses the same
-compiled target baseline when a redesign is requested; it never fills unknown observed values with
-presets and pretends they were measured.
-
-## 1. Establish mode, intent, and evidence
-
-Record the audience, primary task, requested screen or ordered series, platform, input modes,
-viewport constraints, target theme modes, available source artifacts, and requested deliverable.
-Inspect the current manifest, theme, installed packages, ZORA metadata, fonts, and existing
-`zora-designer.md` before prompting.
-
-For an input image or series, decompose each screen into semantic regions. Give each region a stable
-evidence ID, purpose, content/data responsibility, state and interaction needs, accessibility needs,
-and its relationship to other regions. Preserve image order and original dimensions. Do not map by
-appearance alone.
-
-## 2. Build the design in dependency order
-
-Interactive questions and compiler calls follow this exact order. Skip a question only when the
-answer is already supplied or reliably discovered.
-
-1. **Category and intent.** Read `APP_CATEGORIES` and `CATEGORY_PRESETS` from Templates. Show the
-   preset's ordered primary-color and font-family recommendations and explain that they are starting
-   points, not user stereotypes. Defer font activation until its availability and owning loader are
-   verified.
-2. **Primary color.** Offer the preset's first recommended primary color and any verified project
-   brand color. Let the user accept or supply a color. The owner normalizes and validates it.
-3. **Harmony.** Only after primary is resolved, show `recommendedHarmonies` and the installed owner
-   harmony catalog. Preserve the selected canonical identifier.
-4. **Per-mode tone combination.** Show the preset recommendation first, then read all valid choices
-   from `TONE_PAIR_CATALOG`. Resolve light and dark independently with `resolveTonePair`; do not copy
-   a list into prose or code.
-5. **Generated colors.** Call `resolveCategoryDesignPreset` or `compileCategoryDesign`. Inspect
-   generated owner roles and diagnostics; never hand-calculate secondary, accent, severity,
-   background, neutral, or on-colors.
-6. **Computed Surface output.** Inspect `computedTheme.light.surfaceTheme` and
-   `computedTheme.dark.surfaceTheme`, including `ThemeTokens.colors`, `ThemeSemantics`, provenance,
-   selections, and diagnostics. Record `GeneratedColorRole` and `SemanticColorToken` names exactly.
-7. **Composition.** Resolve density, shape, layout, navigation, content hierarchy, states, and exact
-   ZORA elements from metadata. Typography recommendations remain advisory until the chosen font is
-   verified and the owning app/module can load it; never install or bundle a font implicitly.
-8. **Confirmation and output.** Show high-impact choices, their origins, diagnostics, gaps, and the
-   requested artifact. Persist runtime state only through the canonical manifest/contracts.
-
-Use separate light/dark tone pairs and owner compilation even when the two modes share a primary
-seed. Never generate dark mode by inversion.
-
-## 3. Inspect installed owner APIs
-
-Run from the target repository:
+# Owner-Backed Interactive and Template Workflow
 
-```text
-bun .agents/skills/zora-designer/scripts/owner-api.mjs inspect
-```
-
-The output reports installed versions, category presets, tone pairs, component metadata, recipe
-metadata, and required exports. An error names the missing package/export, minimum owner release,
-and update action. There is no fallback calculation.
-
-For deterministic composition, provide JSON to:
-
-```text
-bun .agents/skills/zora-designer/scripts/owner-api.mjs compose design-input.json
-```
-
-The input contains `category`, optional `theme` overrides, `navigator`, `screens`, and optional
-`regions`. Each region has `id`, `requestedCapability`, `screenId`, `parentNodeId`, an optional exact
-`component`, explicit `props`, and `evidenceId`. The helper:
-
-- compiles the category through Templates and the released ZORA compiler;
-- validates exact component names and props against `ZORA_COMPONENT_META`;
-- emits metadata-derived `MissingElement` nodes for unresolved regions;
-- composes the canonical manifest in draft mode while a gap exists;
-- reports `applicationGate: blocked` and owner actions for every gap;
-- preserves Templates and ZORA diagnostics.
-
-The agent remains responsible for semantic matching. A requested component name is an explicit
-decision to validate, not a fuzzy-search request.
+Use this workflow for `interactive`, `screen`, `screens`, and `template`. Ask only about unresolved
+decisions, one decision at a time. Show the owner recommendation first with a short reason. Do not
+silently accept later recommendations because an earlier answer was brief.
 
-## 4. Design one screen or a series
+## 1. Inspect intent and owners
 
-For each screen define purpose, information hierarchy, primary action, navigation relationship,
-data needs, and relevant default/loading/empty/partial/error/offline/success/disabled/hover/pressed/
-selected/focus states. Define narrow and wide behavior where applicable.
-
-For a series also define the shared shell, canonical route topology, state continuity, back/cancel
-behavior, shared recipes and terminology, and one common theme. A concept image series must remain
-ordered and visually coherent. Label every generated image as a concept; replace it with an actual
-runtime capture only after running the manifest.
-
-## 5. Audit a URL, image, or series
-
-For a URL, capture the relevant modes, viewports, and states using a browser/runtime tool. For one
-image or a series, retain original dimensions and input order. Every evidence item records location,
-observation, evidence level, confidence factor, reproduction, and limitations.
-
-Read [audit.md](audit.md), create a criterion input JSON, and run:
+Read repository instructions, an existing manifest or `zora-designer.md`, installed fonts, platform
+configuration, and relevant screens. Run:
 
 ```text
-bun .agents/skills/zora-designer/scripts/audit.mjs audit-input.json zora-designer.md
+bun .agents/skills/zora-designer/scripts/owner-api.mjs inspect
 ```
 
-Invisible behavior remains `not-assessable` unless source, accessibility-tree, browser, or runtime
-evidence supports it. A recommended redesign baseline may use the category workflow but must be
-clearly separated from observed implementation.
-
-## 6. Author a canonical template
-
-Use `composeCategoryAppManifest`, `validateTemplateManifest`, and
-`assertTemplateManifestReady`. Draft output may contain `MissingElement`; release output may not.
-
-When the target repository is `@ankhorage/templates`, scaffold reviewed composition output with:
+The output is the choice source. Do not use remembered categories, color options, tone pairs,
+navigator types, ZORA elements, or events. Resolve explicit user input before project state,
+existing brief values, category recommendations, and global defaults. Record the origin of every
+resolved decision.
+
+## 2. Ask in dependency order
+
+Advance through this sequence. Skip only a value already supplied or reliably discovered.
+
+1. **Category and intent.** Resolve the canonical app category, product name, audience, and primary
+   task. For `screen` and `screens`, audience and primary task are required.
+2. **Platform and theme coverage.** Resolve mobile, desktop, or responsive scope; technology;
+   input modes; target viewport or content constraints; light, dark, or both; and the default mode
+   when relevant.
+3. **Primary color.** Show the category recommendations in owner order and any verified project
+   brand color. Let the user accept one or supply a CSS color. Preserve the brand seed; the owner
+   compiler selects accessible functional steps.
+4. **Harmony.** After primary is resolved, show the category recommendation first and only the
+   harmony identifiers reported by Color Theory. Explain the visual energy and complexity using the
+   owner catalog descriptions.
+5. **Tone pairs.** After harmony is resolved, offer the category's separate light and dark
+   recommendations, followed by mode-compatible owner entries. Explain that `X-on-Y` means accent
+   family on foundation family; structural foregrounds remain independently resolved semantic
+   tokens.
+6. **Typography and profile.** Resolve a verified body font, optional heading pairing, density,
+   shape, motion, and contrast target. Do not install fonts. Offer the category/profile
+   recommendation first and allow the user to accept the recommended system settings together.
+7. **Screens.** Ask for the ordered screen list and purpose of each screen. Then establish the
+   primary action, essential content, required data states, and continuity across the series. Do not
+   generate images yet.
+8. **Navigator.** After the screen topology exists, offer only Contracts navigator types and map
+   every route, initial route, hidden/detail route, back/cancel path, and primary-navigation label.
+9. **Compile and confirm.** Compile both theme modes through the owner helper. Summarize high-impact
+   decisions, origins, diagnostics, unsupported capabilities, screen order, and route topology. Ask
+   for confirmation before creating screen images, code, or a template.
+
+If the user changes an earlier decision, invalidate and revisit only dependent later decisions.
+Changing primary invalidates harmony-derived compilation and tone output but does not erase the
+screen brief. Changing the screen list invalidates navigator confirmation.
+
+## 3. Compile owner output
+
+Provide the resolved `category`, theme overrides, navigator, screens, and region decisions to:
 
 ```text
-bun .agents/skills/zora-designer/scripts/scaffold-template.mjs scaffold-input.json
+bun .agents/skills/zora-designer/scripts/owner-api.mjs compose design-input.json
 ```
 
-The scaffold input provides the ready manifest, category, template ID, label, description, and
-target root. The helper verifies the Templates repository and owner validation, creates a normal
-variant `manifest.ts`, `template.ts`, and `index.ts`, and updates the category registry import and
-definition deterministically. It refuses existing targets, unsafe identifiers, blocked manifests,
-and non-Templates repositories. Review and validate the generated production diff; do not hand-hide
-a systemic skill or owner defect.
-
-## 7. Delivery gates
-
-Before application or release:
-
-- every visible/interactive region has an exact metadata-supported element;
-- every gap has evidence and a linked ZORA owner issue;
-- both modes compile without owner errors;
-- the manifest is owner-validated and release-ready;
-- required concept-image, runtime-capture, or supplied-image capabilities were actually available;
-- target and observed state are clearly separated;
-- `zora-designer.md` is deterministic and contains no runtime authority or copied owner catalogs.
+Use owner-returned theme configuration, generated roles, computed Surface themes, diagnostics,
+component metadata, and manifest composition. Light and dark are independent compilations; never
+derive dark mode by inversion. A failed owner diagnostic remains visible. Do not replace it with
+local math or an undocumented token.
+
+For every region, validate its exact component name, props, allowed-parent relationship, and event
+metadata. Use supported navigation and actions when available. Represent missing capability without
+removing the intended flow or inventing a contract.
+
+## 4. Produce the requested deliverable
+
+- `interactive`: write or return the confirmed `zora-designer.md`; do not produce screen images or
+  implementation unless requested.
+- `screen` or `screens`: read [screens.md](screens.md), create the screen specification, then produce
+  only the requested image, code, or manifest deliverable.
+- `template`: author a complete `AppManifest`, validate it in release mode, generate or extract every
+  required runtime image, and run the Templates scaffolder.
+
+For design-first templates, store reference images under `assets/screens/` and crop only real image
+content into `assets/images/`. For direct authoring, generate application images directly under
+`assets/images/`. Runtime media never references a complete screen image.
+
+## 5. Delivery checks
+
+- every decision is explicit, discovered, or carries a recorded default origin;
+- both theme modes compile without hidden local fallback calculations;
+- the screen model and navigator agree;
+- every selected ZORA node and prop is metadata-supported;
+- supported events/actions are bound and unsupported behavior is recorded;
+- screen generation passes the composition gate;
+- release templates contain one default-exported `createAppManifest()` and bundled media paths;
+- the complete manifest validates against the installed owner contract.

package/dist/tools/skills/assets/zora-designer/scripts/generate-template-catalog.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env bun
+
+import { access, readdir, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+
+import { loadOwnerApis } from './owner-api.mjs';
+
+const CATEGORY_ROOT = 'src/templates/categories';
+
+/*** Regenerate the portable template catalog from canonical template directories. */
+export async function generateTemplateCatalog(targetDirectory = process.cwd(), appCategories) {
+  const root = resolve(targetDirectory);
+  const canonicalAppCategories =
+    appCategories ?? (await loadOwnerApis(root)).contracts.APP_CATEGORIES;
+  const categoriesRoot = join(root, CATEGORY_ROOT);
+  const definitions = [];
+
+  for (const categoryEntry of await readDirectories(categoriesRoot)) {
+    const category = categoryEntry.name.replaceAll('-', '_');
+    if (!canonicalAppCategories.includes(category)) {
+      throw new Error(`Unknown app category directory: ${categoryEntry.name}`);
+    }
+
+    const categoryRoot = join(categoriesRoot, categoryEntry.name);
+    for (const templateEntry of await readDirectories(categoryRoot)) {
+      const manifestPath = join(categoryRoot, templateEntry.name, 'createAppManifest.ts');
+      if (!(await pathExists(manifestPath))) continue;
+      definitions.push({
+        category,
+        categoryDirectory: categoryEntry.name,
+        slug: templateEntry.name,
+      });
+    }
+  }
+
+  definitions.sort((left, right) =>
+    `${left.category}/${left.slug}`.localeCompare(`${right.category}/${right.slug}`),
+  );
+
+  const imports = definitions
+    .map(
+      (definition, index) =>
+        `import createAppManifest${index} from './categories/${definition.categoryDirectory}/${definition.slug}/createAppManifest';`,
+    )
+    .join('\n');
+  const entries = definitions
+    .map(
+      (definition, index) => `  {
+    category: '${definition.category}',
+    slug: '${definition.slug}',
+    sourceRoot: '${CATEGORY_ROOT}/${definition.categoryDirectory}/${definition.slug}',
+    createAppManifest: createAppManifest${index},
+  },`,
+    )
+    .join('\n');
+  const definitionsSource = definitions.length === 0 ? '[]' : `[\n${entries}\n]`;
+
+  const source = `${imports}${imports ? '\n\n' : ''}import type { TemplateDefinition } from './catalog';
+
+export const TEMPLATE_DEFINITIONS: readonly TemplateDefinition[] = ${definitionsSource};
+`;
+
+  const outputPath = join(root, 'src/templates/catalog.generated.ts');
+  await writeFile(outputPath, source, 'utf8');
+  return { outputPath, templateCount: definitions.length };
+}
+
+/*** Read child directories in stable lexical order. */
+async function readDirectories(directory) {
+  return (await readdir(directory, { withFileTypes: true }))
+    .filter((entry) => entry.isDirectory())
+    .sort((left, right) => left.name.localeCompare(right.name));
+}
+
+/*** Return whether a filesystem path exists. */
+async function pathExists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+if (import.meta.main) {
+  const targetDirectory = process.argv[2] ?? process.cwd();
+  const result = await generateTemplateCatalog(targetDirectory);
+  console.log(`Generated ${result.templateCount} template catalog entries.`);
+}

package/dist/tools/skills/assets/zora-designer/scripts/owner-api.mjs

@@ -5,11 +5,23 @@ import { dirname, join, parse, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 
 const OWNER_RELEASES = {
+  colorTheory: { packageName: '@ankhorage/color-theory', minimumVersion: '0.3.0' },
+  contracts: { packageName: '@ankhorage/contracts', minimumVersion: '8.2.0' },
   templates: { packageName: '@ankhorage/templates', minimumVersion: '8.0.0' },
   zora: { packageName: '@ankhorage/zora', minimumVersion: '4.0.0' },
 };
 
 const OWNER_REQUIREMENTS = {
+  colorTheory: {
+    ...OWNER_RELEASES.colorTheory,
+    specifier: '@ankhorage/color-theory',
+    exports: ['COLOR_HARMONIES', 'COLOR_HARMONY_CATALOG'],
+  },
+  contracts: {
+    ...OWNER_RELEASES.contracts,
+    specifier: '@ankhorage/contracts',
+    exports: ['APP_CATEGORIES', 'NAVIGATOR_TYPES'],
+  },
   templates: {
     ...OWNER_RELEASES.templates,
     specifier: '@ankhorage/templates',
@@ -45,10 +57,14 @@ export async function loadOwnerApis(targetDirectory = process.cwd()) {
   }
 
   return {
+    colorTheory: loaded.colorTheory.module,
+    contracts: loaded.contracts.module,
     templates: loaded.templates.module,
     zoraTheme: loaded.zoraTheme.module,
     zoraMetadata: loaded.zoraMetadata.module,
     versions: {
+      colorTheory: loaded.colorTheory.version,
+      contracts: loaded.contracts.version,
       templates: loaded.templates.version,
       zora: loaded.zoraTheme.version,
     },
@@ -58,22 +74,36 @@ export async function loadOwnerApis(targetDirectory = process.cwd()) {
 /*** Return installed catalogs and metadata names without copying owner definitions. */
 export async function inspectOwnerApis(targetDirectory = process.cwd()) {
   const owners = await loadOwnerApis(targetDirectory);
+  const componentMetadata = Object.values(owners.zoraMetadata.ZORA_COMPONENT_META);
   return {
     versions: owners.versions,
-    categories: Object.values(owners.templates.CATEGORY_PRESETS).map((preset) => ({
-      category: preset.category,
-      label: preset.label,
-      recommendedPrimaryColors: preset.recommendedPrimaryColors,
-      recommendedHarmonies: preset.recommendedHarmonies,
-      tonePairs: preset.tonePairs,
-    })),
+    appCategories: owners.contracts.APP_CATEGORIES,
+    categoryPresets: owners.templates.CATEGORY_PRESETS,
+    harmonyIds: owners.colorTheory.COLOR_HARMONIES,
+    harmonies: owners.colorTheory.COLOR_HARMONY_CATALOG,
     tonePairs: owners.templates.TONE_PAIR_CATALOG,
-    components: Object.keys(owners.zoraMetadata.ZORA_COMPONENT_META).sort(),
+    navigatorTypes: owners.contracts.NAVIGATOR_TYPES,
+    components: componentMetadata.map((meta) => meta.name).sort(),
+    events: componentMetadata
+      .flatMap((meta) =>
+        Object.values(meta.events ?? {}).map((event) => ({
+          component: meta.name,
+          eventType: event.eventType,
+          label: event.label,
+          description: event.description,
+          payloadFields: event.payloadFields,
+        })),
+      )
+      .sort((left, right) =>
+        `${left.component}:${left.eventType}`.localeCompare(
+          `${right.component}:${right.eventType}`,
+        ),
+      ),
     themeRecipes: Object.keys(owners.zoraMetadata.ZORA_THEME_RECIPE_META).sort(),
   };
 }
 
-/*** Compile category design, validate region nodes, and compose one canonical draft or release manifest. */
+/*** Compose one design without turning missing runtime/UI capabilities into a design blocker. */
 export async function composeDesign(input, targetDirectory = process.cwd()) {
   const owners = await loadOwnerApis(targetDirectory);
   assertRecord(input, 'Design input');
@@ -90,7 +120,6 @@ export async function composeDesign(input, targetDirectory = process.cwd()) {
   const design = owners.templates.compileCategoryDesign(input.category, input.theme ?? {});
   const { computedTheme, ...resolvedDesign } = design;
   const requestedAuthoringState = input.authoringState === 'release' ? 'release' : 'draft';
-  const authoringState = regionResult.gaps.length === 0 ? requestedAuthoringState : 'draft';
   const composition = owners.templates.composeCategoryAppManifest({
     category: input.category,
     name: input.name,
@@ -103,14 +132,14 @@ export async function composeDesign(input, targetDirectory = process.cwd()) {
     modules: input.modules,
     modulesConfig: input.modulesConfig,
     theme: input.theme,
-    authoringState,
+    authoringState: requestedAuthoringState,
   });
   const ownerDiagnostics = [
     ...design.diagnostics,
     ...computedTheme.diagnostics,
     ...composition.diagnostics,
   ];
-  const blocked = regionResult.gaps.length > 0 || composition.status === 'blocked';
+  const blockers = ownerDiagnostics.filter((diagnostic) => diagnostic.severity === 'error');
 
   return {
     owners: owners.versions,
@@ -118,14 +147,15 @@ export async function composeDesign(input, targetDirectory = process.cwd()) {
     computedTheme,
     composition,
     regionDiagnostics: regionResult.diagnostics,
+    capabilityGaps: regionResult.gaps,
     ownerDiagnostics,
     requestedAuthoringState,
-    applicationGate: blocked ? 'blocked' : 'pass',
-    blockers: regionResult.gaps,
+    applicationGate: composition.status === 'blocked' ? 'blocked' : 'pass',
+    blockers,
   };
 }
 
-/*** Resolve explicit region-to-component decisions and insert validated nodes into cloned screens. */
+/*** Resolve explicit region decisions using exact metadata or a visible non-blocking Box placeholder. */
 export function resolveRegionNodes(screens, regions, componentMeta) {
   const resolvedScreens = structuredClone(screens);
   const diagnostics = [];
@@ -152,7 +182,6 @@ export function resolveRegionNodes(screens, regions, componentMeta) {
   return { screens: resolvedScreens, diagnostics, gaps };
 }
 
-/*** Resolve one exact metadata-backed component or the owner-defined MissingElement placeholder. */
 function resolveRegionNode(region, componentMeta) {
   const component = typeof region.component === 'string' ? region.component : null;
   const meta = component === null ? null : componentMeta[component];
@@ -170,36 +199,30 @@ function resolveRegionNode(region, componentMeta) {
     };
   }
 
-  const missingMeta = componentMeta.MissingElement;
-  if (!missingMeta || missingMeta.manifestPolicy?.kind !== 'unresolved-element') {
-    throw new Error(
-      'Installed @ankhorage/zora metadata does not expose the canonical MissingElement contract.',
-    );
+  const placeholderMeta = componentMeta.Box;
+  if (!placeholderMeta?.directManifestNode) {
+    throw new Error('Installed @ankhorage/zora metadata does not expose Box as a manifest node.');
   }
-  const props = {
-    ...(missingMeta.blueprint?.defaultProps ?? {}),
-    requestedCapability: region.requestedCapability,
-    reason:
-      typeof region.reason === 'string' && region.reason.trim() !== ''
-        ? region.reason
-        : `No exact metadata-supported ZORA element was selected for region "${region.id}".`,
-    ...(typeof region.evidenceId === 'string' ? { evidenceId: region.evidenceId } : {}),
-  };
-  assertSupportedProps(props, missingMeta, region.id);
+  const reason =
+    typeof region.reason === 'string' && region.reason.trim() !== ''
+      ? region.reason
+      : `No exact metadata-supported ZORA element was selected for region "${region.id}".`;
   const gap = {
-    id: `missing-element:${region.id}`,
-    scope: 'composition',
-    owner: '@ankhorage/zora',
+    id: `capability-gap:${region.id}`,
+    scope: 'capability',
     regionId: region.id,
     requestedCapability: region.requestedCapability,
     evidenceId: region.evidenceId ?? null,
-    ownerIssueUrl: region.ownerIssueUrl ?? null,
-    reason: props.reason,
-    unblockCondition: 'Replace MissingElement with a released exact ZORA element and revalidate.',
+    reason,
   };
   return {
-    node: { id: region.id, type: missingMeta.name, props },
-    diagnostic: { regionId: region.id, status: 'missing', component: missingMeta.name, ...gap },
+    node: { id: region.id, type: placeholderMeta.name, props: {} },
+    diagnostic: {
+      regionId: region.id,
+      status: 'placeholder',
+      component: placeholderMeta.name,
+      ...gap,
+    },
     gap,
   };
 }