@ankhorage/devtools 1.12.1 → 1.14.0

package/dist/tools/skills/assets/zora-designer/SKILL.md

@@ -1,16 +1,16 @@
 ---
 name: zora-designer
 description: >
-  Configure an owner-backed application design, generate one screen or a coherent screen series,
-  audit supplied evidence, and author portable Ankhorage templates. Use for category-driven design
-  decisions, ZORA screen generation, visual audits, or template creation.
+  Configure an owner-backed application design, generate or recognize screens, audit supplied
+  evidence, and author portable Ankhorage templates. Use for category-driven design decisions,
+  ZORA screen generation or reconstruction, visual audits, or template creation.
 ---
 
 # ZORA Designer
 
-Design, audit, and author through the target repository's released owner APIs. The complete
-`AppManifest` is runtime authority; `zora-designer.md` and generated screen images are design
-evidence.
+Design, recognize, audit, and author through the target repository's released owner APIs. The
+complete `AppManifest` is runtime authority; `zora-designer.md` and generated screen images are
+design evidence.
 
 ## Route the request
 
@@ -20,6 +20,10 @@ evidence.
   screen.
 - `screens`: resolve the configuration, then read [screens.md](references/screens.md) and design an
   ordered series with shared navigation, state, geometry, and tokens.
+- `recognize`: when the user supplies an existing UI screenshot/screen design and asks to
+  reconstruct it, determine ZORA components, or convert it to a manifest screen, read
+  [screen-analysis.md](references/screen-analysis.md) and run programmatic recognition before
+  free-form visual interpretation.
 - `audit`: read [audit.md](references/audit.md) and evaluate supplied image or runtime evidence.
 - `template`: resolve the configuration and screen model, then author one portable template through
   the workflow below.
@@ -42,6 +46,13 @@ types, ZORA elements, events, recipes, and version provenance. Never copy owner
 schemas, token inventories, color algorithms, action types, or manifest implementations into this
 skill.
 
+The inspection composes metadata-only descriptors from every installed `@ankhorage/zora-*` plugin;
+use those plugin elements exactly like ZORA core elements and keep their package provenance.
+
+For supplied-screen reconstruction, continue through `recognize` and treat the local analyzer's
+`ScreenSpec`, visual graph, confidence, alternatives, and unresolved diagnostics as the structural
+evidence baseline. Do not ask an image model to redo deterministic geometry/component matching.
+
 Compile chosen values with the same helper before composing screens. Inspect both computed modes,
 including their resolved Surface themes and all owner diagnostics. Never hand-calculate a value the
 owner exposes.
@@ -49,9 +60,15 @@ owner exposes.
 ## Preserve the complete UX
 
 For every screen region, prefer the exact semantic ZORA element supported by current metadata.
-Visual resemblance alone is insufficient. If no exact element exists, preserve the requested UX
-with an obvious supported placeholder such as a secondary-surface `Box`, and record the capability
-gap. Do not invent props, application components, or successful behavior.
+Visual resemblance alone is insufficient. If programmatic recognition leaves multiple plausible
+candidates, resolve them from semantic responsibility and stated product intent while preserving the
+ranked alternatives as evidence.
+
+If no exact element exists, preserve the requested UX with an explicit owner-supported unresolved
+placeholder when available, and record the capability gap. For ordinary design composition where no
+unresolved manifest element is applicable, use an obvious supported placeholder such as a
+secondary-surface `Box` and record the capability gap. Do not invent props, application components,
+or successful behavior.
 
 Bind every interaction expressible by installed Contracts and ZORA event metadata. Leave an
 unsupported interaction visibly present and explicitly unbound without blocking unrelated design
@@ -95,6 +112,8 @@ barrels.
 
 - confirm the interactive decision sequence completed or the user explicitly accepted remaining
   recommendations;
+- for supplied image reconstruction, run `recognize` before semantic refinement and retain its
+  confidence/alternative/gap evidence;
 - compile light and dark independently through installed owner APIs;
 - validate selected ZORA nodes, props, events, actions, and complete manifest contracts;
 - run the screen composition gate from [screens.md](references/screens.md) before returning screen

package/dist/tools/skills/assets/zora-designer/agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: 'ZORA Designer'
-  short_description: 'Design, audit, and author Ankhorage screens and templates through ZORA.'
-  default_prompt: 'Use $zora-designer to design, audit, or author this Ankhorage interface.'
+  short_description: 'Design, recognize, audit, and author Ankhorage screens and templates through ZORA.'
+  default_prompt: 'Use $zora-designer to design, recognize, audit, or author this Ankhorage interface.'
 policy:
   allow_implicit_invocation: true

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

@@ -0,0 +1,115 @@
+# Supplied Screen Recognition
+
+Read this reference when the user supplies an existing UI screenshot or screen design and asks to
+reconstruct it, determine its ZORA components, convert it to a manifest screen, or use it as the
+starting point for a redesigned screen.
+
+This path analyzes supplied evidence. It does not replace `screen` or `screens` generation.
+
+## Run deterministic recognition first
+
+Before free-form visual interpretation, inspect the released owners and run the local analyzer from
+the target repository:
+
+```text
+bun .agents/skills/zora-designer/scripts/owner-api.ts inspect
+bun .agents/skills/zora-designer/scripts/analyze-screen.ts screen-analysis-input.json
+```
+
+The analyzer uses the current composed ZORA metadata, including every installed
+`@ankhorage/zora-*` plugin, and delegates image processing to released
+`@ankhorage/utility/image`:
+
+```text
+supplied image
+  -> Sharp normalization
+  -> OpenCV geometry and visual graph
+  -> optional local Tesseract OCR
+  -> owner-metadata component matching
+  -> global tree validation
+  -> Contracts ScreenSpec
+```
+
+No remote model or API is required for this pass.
+
+## Input
+
+Write one temporary JSON input file in the target repository. Image paths are resolved from the
+target repository root.
+
+```json
+{
+  "image": "design/screens/home.png",
+  "screen": {
+    "id": "home",
+    "name": "Home",
+    "title": "Home"
+  },
+  "minConfidence": 0.42
+}
+```
+
+OCR is supplementary. Enable it only when local trained data is available and text evidence helps
+distinguish visually similar components:
+
+```json
+{
+  "image": "design/screens/home.png",
+  "screen": { "id": "home", "name": "Home" },
+  "ocr": {
+    "langPath": "./tessdata",
+    "language": "eng"
+  }
+}
+```
+
+Geometry-only analysis remains valid if OCR setup or recognition fails; the output records an OCR
+diagnostic instead of replacing the visual graph.
+
+## Local engine boundary
+
+`@ankhorage/utility` owns the image implementation. The target authoring repository supplies the
+optional native/WASM engines required by the recognition path. If they are absent, install them as
+development tooling:
+
+```text
+bun add -D sharp @techstark/opencv-js
+```
+
+Do not add a copied matcher, OpenCV wrapper, fallback parser, remote vision service, or alternate
+component catalogue to the skill.
+
+## Treat the result as evidence
+
+The analyzer returns:
+
+- canonical Contracts `ScreenSpec`;
+- visual graph evidence;
+- aggregate confidence;
+- ranked component candidates by region;
+- unresolved diagnostics;
+- the exact composed component names and owner/plugin version provenance used for the pass.
+
+Use the generated `ScreenSpec` as the structural baseline. Do not discard a high-confidence exact
+metadata match merely because another component looks visually similar.
+
+When confidence is low, preserve the analyzer's alternatives and resolve the ambiguity using the
+screen's semantic responsibility and the user's stated product intent. If metadata declares an
+unresolved element, the analyzer uses that explicit owner-owned gap instead of inventing a ZORA
+component or prop.
+
+## Refine only what pixels cannot prove
+
+After recognition, reason about the parts a static image cannot establish reliably:
+
+- purpose and primary task;
+- actions and event bindings;
+- navigation and back/cancel behavior;
+- state transitions and validation;
+- data sources and bindings;
+- accessibility and focus behavior;
+- responsive behavior beyond the observed viewport;
+- loading, empty, error, offline, pressed, selected, and other unseen states.
+
+Then run the normal `screen` composition rules and owner-backed manifest validation. A screenshot is
+visual evidence, not proof of runtime behavior.

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

@@ -4,6 +4,11 @@ Read this reference for `screen` and `screens` after the interactive configurati
 Generated images are concept evidence; the manifest and ZORA metadata remain implementation
 authority.
 
+When the starting point is a supplied existing screen image, run `recognize` first through
+[screen-analysis.md](screen-analysis.md). Treat its canonical `ScreenSpec`, visual graph, confidence,
+alternatives, and unresolved diagnostics as structural evidence, then use this reference for the
+semantic and behavioral refinement that pixels cannot establish.
+
 ## Preconditions
 
 Do not generate or implement a screen until these are resolved:
@@ -30,6 +35,10 @@ For every screen record:
 6. safe areas, keyboard/overlay behavior, scroll ownership, and narrow/wide behavior;
 7. every SVG icon and real image region, its reusable asset ID, and its intended manifest usage.
 
+For a recognized supplied image, preserve every high-confidence metadata-backed subtree unless the
+user's stated intent provides stronger semantic evidence. Resolve ambiguous candidates explicitly;
+do not silently replace the analyzer's tree with a visually similar primitive decomposition.
+
 Read [runtime-assets.md](runtime-assets.md). Produce and inspect the separate icons and images before
 concept rendering, use them as screen references, and deliver their checked bundle with the screens.
 

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

@@ -18,6 +18,9 @@ navigator types, ZORA elements, or events. Resolve explicit user input before pr
 existing brief values, category recommendations, and global defaults. Record the origin of every
 resolved decision.
 
+Installed `@ankhorage/zora-*` packages contribute their metadata-only plugin descriptors to this
+same composed element catalog; do not maintain a second plugin list in the skill.
+
 ## 2. Ask in dependency order
 
 Advance through this sequence. Skip only a value already supplied or reliably discovered.

package/dist/tools/skills/assets/zora-designer/scripts/analyze-screen.ts

@@ -0,0 +1,320 @@
+#!/usr/bin/env bun
+
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { loadOwnerApis } from './owner-api.ts';
+
+const DEVTOOLS_PACKAGE_NAME = '@ankhorage/devtools';
+const UTILITY_PACKAGE_NAME = '@ankhorage/utility';
+const REQUIRED_IMAGE_ENGINES = ['sharp', '@techstark/opencv-js'] as const;
+
+interface ScreenOcr {
+  readonly recognizeAsync: (image: Uint8Array) => Promise<readonly unknown[]>;
+  readonly terminateAsync?: () => Promise<void>;
+}
+
+interface UtilityImageApi {
+  readonly analyzeScreenImageAsync: (
+    image: string,
+    options: Readonly<Record<string, unknown>>,
+  ) => Promise<unknown>;
+  readonly createTesseractScreenOcrAsync: (options: {
+    readonly langPath: string;
+    readonly language?: string;
+  }) => Promise<ScreenOcr>;
+}
+
+interface AnalyzeScreenInput {
+  readonly image: string;
+  readonly screen: {
+    readonly id: string;
+    readonly name: string;
+    readonly title?: string;
+    readonly description?: string;
+  };
+  readonly minConfidence?: number;
+  readonly ocr?: {
+    readonly langPath: string;
+    readonly language?: string;
+  };
+}
+
+interface ScreenAnalysisRuntime {
+  readonly api: UtilityImageApi;
+  readonly utilityVersion: string;
+}
+
+/*** Analyze one supplied UI screen with current owner metadata and the released Utility image pipeline. */
+export async function analyzeScreenAsync(
+  input: unknown,
+  targetDirectory = process.cwd(),
+): Promise<Record<string, unknown>> {
+  const parsedInput = readAnalyzeScreenInput(input);
+  const owners = await loadOwnerApis(targetDirectory);
+  const components = readComponentCatalog(owners.zoraMetadata.ZORA_COMPONENT_META);
+  const unresolvedComponentName = resolveUnresolvedComponentName(components);
+  const runtime = await loadScreenAnalysisRuntime(targetDirectory);
+  const ocr = await createOptionalOcr(runtime.api, parsedInput.ocr);
+
+  try {
+    const analysis = await runtime.api.analyzeScreenImageAsync(
+      resolve(targetDirectory, parsedInput.image),
+      {
+        screen: parsedInput.screen,
+        components,
+        ...(unresolvedComponentName ? { unresolvedComponentName } : {}),
+        ...(parsedInput.minConfidence === undefined
+          ? {}
+          : { minConfidence: parsedInput.minConfidence }),
+        ...(ocr ? { ocr } : {}),
+      },
+    );
+    assertRecord(analysis, 'Utility screen analysis result');
+    return {
+      owners: { ...owners.versions, utility: runtime.utilityVersion },
+      componentCount: components.length,
+      componentNames: components.map((component) => String(component.name)).sort(),
+      ...(unresolvedComponentName ? { unresolvedComponentName } : {}),
+      ...analysis,
+    };
+  } finally {
+    await ocr?.terminateAsync?.();
+  }
+}
+
+/*** Load Utility image analysis through the installed Devtools dependency boundary. */
+async function loadScreenAnalysisRuntime(targetDirectory: string): Promise<ScreenAnalysisRuntime> {
+  const devtoolsManifestPath = await resolveDevtoolsManifestPath(targetDirectory);
+  const devtoolsRequire = createRequire(devtoolsManifestPath);
+  let utilityManifestPath: string;
+  try {
+    utilityManifestPath = devtoolsRequire.resolve(`${UTILITY_PACKAGE_NAME}/package.json`);
+  } catch (error) {
+    throw new Error(
+      'zora-designer screen analysis requires @ankhorage/utility 0.5.x through the installed @ankhorage/devtools dependency. Update Devtools through the normal release/Renovate workflow and retry.',
+      { cause: error },
+    );
+  }
+
+  assertRequiredImageEngines(devtoolsRequire);
+  const utilityManifest: unknown = JSON.parse(await readFile(utilityManifestPath, 'utf8'));
+  assertRecord(utilityManifest, '@ankhorage/utility package manifest');
+  assertNonEmptyString(utilityManifest.version, '@ankhorage/utility version');
+
+  let modulePath: string;
+  try {
+    modulePath = devtoolsRequire.resolve(`${UTILITY_PACKAGE_NAME}/image`);
+  } catch (error) {
+    throw new Error(
+      'Installed @ankhorage/utility does not expose the required public /image subpath. Update @ankhorage/devtools so it selects Utility 0.5.x or newer and retry.',
+      { cause: error },
+    );
+  }
+  const module: unknown = await import(pathToFileURL(modulePath).href);
+  assertUtilityImageApi(module);
+  return { api: module, utilityVersion: utilityManifest.version };
+}
+
+/*** Resolve the installed Devtools package manifest used as the dependency-resolution anchor. */
+async function resolveDevtoolsManifestPath(targetDirectory: string): Promise<string> {
+  const targetRoot = resolve(targetDirectory);
+  const targetManifestPath = join(targetRoot, 'package.json');
+  const targetManifest: unknown = JSON.parse(await readFile(targetManifestPath, 'utf8'));
+  assertRecord(targetManifest, 'Target package manifest');
+  if (targetManifest.name === DEVTOOLS_PACKAGE_NAME) {
+    return targetManifestPath;
+  }
+
+  const installedManifestPath = join(
+    targetRoot,
+    'node_modules',
+    '@ankhorage',
+    'devtools',
+    'package.json',
+  );
+  try {
+    await readFile(installedManifestPath, 'utf8');
+    return installedManifestPath;
+  } catch (error) {
+    throw new Error(
+      'zora-designer screen analysis requires the target repository to have @ankhorage/devtools installed. Run the normal Devtools synchronization/install workflow and retry.',
+      { cause: error },
+    );
+  }
+}
+
+/*** Require the local deterministic engines used by Utility without making them global Devtools runtime dependencies. */
+function assertRequiredImageEngines(devtoolsRequire: ReturnType<typeof createRequire>): void {
+  const missing = REQUIRED_IMAGE_ENGINES.filter((packageName) => {
+    try {
+      devtoolsRequire.resolve(packageName);
+      return false;
+    } catch {
+      return true;
+    }
+  });
+  if (missing.length > 0) {
+    throw new Error(
+      `zora-designer screen analysis requires local image engines ${missing.join(', ')}. Install the screen-analysis engines in the target repository with "bun add -D sharp @techstark/opencv-js" and retry.`,
+    );
+  }
+}
+
+/*** Create supplementary local OCR while converting setup failures into evidence rather than geometry blockers. */
+async function createOptionalOcr(
+  api: UtilityImageApi,
+  options: AnalyzeScreenInput['ocr'],
+): Promise<ScreenOcr | undefined> {
+  if (!options) return undefined;
+  try {
+    return await api.createTesseractScreenOcrAsync(options);
+  } catch (error) {
+    const rejection = error instanceof Error ? error : new Error(String(error));
+    return { recognizeAsync: () => Promise.reject(rejection) };
+  }
+}
+
+/*** Preserve the full composed owner metadata while validating the fields required by the Utility matcher. */
+function readComponentCatalog(value: unknown): Record<string, unknown>[] {
+  assertRecord(value, 'Composed ZORA component metadata');
+  return Object.values(value)
+    .filter((component) => component !== undefined)
+    .map((component, index) => {
+      assertRecord(component, `ZORA component metadata[${index}]`);
+      assertNonEmptyString(component.name, `ZORA component metadata[${index}].name`);
+      assertComponentCategory(component.category, `ZORA component metadata[${index}].category`);
+      if (typeof component.directManifestNode !== 'boolean') {
+        throw new Error(`ZORA component metadata[${index}].directManifestNode must be a boolean.`);
+      }
+      assertStringArray(
+        component.allowedChildren,
+        `ZORA component metadata[${index}].allowedChildren`,
+      );
+      assertRecord(component.props, `ZORA component metadata[${index}].props`);
+      return component;
+    });
+}
+
+/*** Resolve the owner-declared unresolved manifest component without hard-coding a ZORA component name. */
+function resolveUnresolvedComponentName(
+  components: readonly Record<string, unknown>[],
+): string | undefined {
+  const unresolved = components.find((component) => {
+    const policy = component.manifestPolicy;
+    return isRecord(policy) && policy.kind === 'unresolved-element';
+  });
+  return typeof unresolved?.name === 'string' ? unresolved.name : undefined;
+}
+
+/*** Parse and validate portable JSON input for one recognition operation. */
+function readAnalyzeScreenInput(value: unknown): AnalyzeScreenInput {
+  assertRecord(value, 'Screen analysis input');
+  assertNonEmptyString(value.image, 'image');
+  assertRecord(value.screen, 'screen');
+  assertNonEmptyString(value.screen.id, 'screen.id');
+  assertNonEmptyString(value.screen.name, 'screen.name');
+  assertOptionalString(value.screen.title, 'screen.title');
+  assertOptionalString(value.screen.description, 'screen.description');
+  const minConfidence = readMinConfidence(value.minConfidence);
+  const ocr = readOcrOptions(value.ocr);
+
+  return {
+    image: value.image,
+    screen: {
+      id: value.screen.id,
+      name: value.screen.name,
+      ...(value.screen.title === undefined ? {} : { title: value.screen.title }),
+      ...(value.screen.description === undefined ? {} : { description: value.screen.description }),
+    },
+    ...(minConfidence === undefined ? {} : { minConfidence }),
+    ...(ocr === undefined ? {} : { ocr }),
+  };
+}
+
+/*** Read one optional confidence threshold constrained to the Utility matcher interval. */
+function readMinConfidence(value: unknown): number | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0 || value > 1) {
+    throw new Error('minConfidence must be a finite number from 0 through 1.');
+  }
+  return value;
+}
+
+/*** Read optional local OCR configuration without making OCR a geometry prerequisite. */
+function readOcrOptions(value: unknown): AnalyzeScreenInput['ocr'] {
+  if (value === undefined) return undefined;
+  assertRecord(value, 'ocr');
+  assertNonEmptyString(value.langPath, 'ocr.langPath');
+  assertOptionalString(value.language, 'ocr.language');
+  return {
+    langPath: value.langPath,
+    ...(value.language === undefined ? {} : { language: value.language }),
+  };
+}
+
+/*** Narrow the released Utility image subpath to the two capabilities used by the skill. */
+function assertUtilityImageApi(value: unknown): asserts value is UtilityImageApi {
+  assertRecord(value, '@ankhorage/utility/image');
+  if (typeof value.analyzeScreenImageAsync !== 'function') {
+    throw new Error('@ankhorage/utility/image must export analyzeScreenImageAsync.');
+  }
+  if (typeof value.createTesseractScreenOcrAsync !== 'function') {
+    throw new Error('@ankhorage/utility/image must export createTesseractScreenOcrAsync.');
+  }
+}
+
+/*** Require one current ZORA component category. */
+function assertComponentCategory(value: unknown, label: string): void {
+  if (!['foundation', 'component', 'pattern', 'layout'].includes(String(value))) {
+    throw new Error(`${label} must be a current ZORA component category.`);
+  }
+}
+
+/*** Require an array containing only strings. */
+function assertStringArray(value: unknown, label: string): asserts value is string[] {
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string')) {
+    throw new Error(`${label} must be a string array.`);
+  }
+}
+
+/*** Require an optional non-empty string when present. */
+function assertOptionalString(value: unknown, label: string): asserts value is string | undefined {
+  if (value !== undefined) assertNonEmptyString(value, label);
+}
+
+/*** Require an object-shaped value. */
+function assertRecord(value: unknown, label: string): asserts value is Record<string, unknown> {
+  if (!isRecord(value)) throw new Error(`${label} must be an object.`);
+}
+
+/*** Narrow an unknown value to a record. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/*** Require a non-empty string. */
+function assertNonEmptyString(value: unknown, label: string): asserts value is string {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new Error(`${label} must be a non-empty string.`);
+  }
+}
+
+/*** Run the portable recognition command when executed directly. */
+async function main(): Promise<void> {
+  const [inputPath] = process.argv.slice(2);
+  if (!inputPath) {
+    throw new Error('Usage: analyze-screen.ts <screen-analysis-input.json>');
+  }
+  const input: unknown = JSON.parse(await readFile(inputPath, 'utf8'));
+  console.log(JSON.stringify(await analyzeScreenAsync(input), null, 2));
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}

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

@@ -58,7 +58,7 @@ interface ZoraThemeApi extends Record<string, unknown> {
 }
 
 interface EventMetadata extends Record<string, unknown> {
-  description: string;
+  description?: string;
   eventType: string;
   label: string;
   payloadFields?: unknown;
@@ -84,6 +84,10 @@ interface RecipeMetadata extends Record<string, unknown> {
 }
 
 interface ZoraMetadataApi extends Record<string, unknown> {
+  composeZoraPluginMetadata: (plugins: readonly Record<string, unknown>[]) => {
+    componentMeta: Record<string, ComponentMetadata | undefined>;
+  };
+  ZORA_CORE_PLUGIN_METADATA: Record<string, unknown>;
   ZORA_COMPONENT_META: Record<string, ComponentMetadata | undefined>;
   ZORA_THEME_RECIPE_META: Record<string, RecipeMetadata | undefined>;
 }
@@ -119,7 +123,7 @@ const OWNER_RELEASES = {
   colorTheory: { packageName: '@ankhorage/color-theory', minimumVersion: '0.3.0' },
   contracts: { packageName: '@ankhorage/contracts', minimumVersion: '10.1.0' },
   templates: { packageName: '@ankhorage/templates', minimumVersion: '9.3.0' },
-  zora: { packageName: '@ankhorage/zora', minimumVersion: '4.2.0' },
+  zora: { packageName: '@ankhorage/zora', minimumVersion: '4.3.0' },
 };
 
 const OWNER_REQUIREMENTS = {
@@ -155,7 +159,12 @@ const OWNER_REQUIREMENTS = {
   zoraMetadata: {
     ...OWNER_RELEASES.zora,
     specifier: '@ankhorage/zora/metadata',
-    exports: ['ZORA_COMPONENT_META', 'ZORA_THEME_RECIPE_META'],
+    exports: [
+      'composeZoraPluginMetadata',
+      'ZORA_COMPONENT_META',
+      'ZORA_CORE_PLUGIN_METADATA',
+      'ZORA_THEME_RECIPE_META',
+    ],
   },
 };
 
@@ -171,27 +180,81 @@ export async function loadOwnerApis(targetDirectory = process.cwd()) {
   const templates = await loadOwnerModule(targetDirectory, OWNER_REQUIREMENTS.templates);
   const zoraTheme = await loadOwnerModule(targetDirectory, OWNER_REQUIREMENTS.zoraTheme);
   const zoraMetadata = await loadOwnerModule(targetDirectory, OWNER_REQUIREMENTS.zoraMetadata);
+  const installedPluginMetadata = await loadInstalledZoraPluginMetadata(targetDirectory);
   assertColorTheoryApi(colorTheory.module);
   assertContractsApi(contracts.module);
   assertTemplatesApi(templates.module);
   assertZoraThemeApi(zoraTheme.module);
   assertZoraMetadataApi(zoraMetadata.module);
+  const composedZoraMetadata = zoraMetadata.module.composeZoraPluginMetadata([
+    zoraMetadata.module.ZORA_CORE_PLUGIN_METADATA,
+    ...installedPluginMetadata.map((entry) => entry.metadata),
+  ]);
+  assertRecord(composedZoraMetadata, 'composed ZORA plugin metadata');
+  assertRecord(composedZoraMetadata.componentMeta, 'composed ZORA component metadata');
 
   return {
     colorTheory: colorTheory.module,
     contracts: contracts.module,
     templates: templates.module,
     zoraTheme: zoraTheme.module,
-    zoraMetadata: zoraMetadata.module,
+    zoraMetadata: {
+      ...zoraMetadata.module,
+      ZORA_COMPONENT_META: composedZoraMetadata.componentMeta,
+    },
     versions: {
       colorTheory: colorTheory.version,
       contracts: contracts.version,
       templates: templates.version,
       zora: zoraTheme.version,
+      plugins: Object.fromEntries(
+        installedPluginMetadata.map((entry) => [entry.packageName, entry.version]),
+      ),
     },
   };
 }
 
+/*** Load metadata-only descriptors for every installed ZORA plugin declared by the target package. */
+async function loadInstalledZoraPluginMetadata(
+  targetDirectory: string,
+): Promise<{ metadata: Record<string, unknown>; packageName: string; version: string }[]> {
+  const targetManifestPath = join(resolve(targetDirectory), 'package.json');
+  const targetManifest: unknown = JSON.parse(await readFile(targetManifestPath, 'utf8'));
+  assertRecord(targetManifest, 'Target package manifest');
+  const packageNames = new Set<string>();
+  if (typeof targetManifest.name === 'string') packageNames.add(targetManifest.name);
+  for (const field of ['dependencies', 'devDependencies', 'peerDependencies']) {
+    const dependencies = targetManifest[field];
+    if (!isRecord(dependencies)) continue;
+    for (const packageName of Object.keys(dependencies)) packageNames.add(packageName);
+  }
+
+  const loaded: { metadata: Record<string, unknown>; packageName: string; version: string }[] = [];
+  for (const packageName of [...packageNames].filter(isZoraPluginPackage).sort()) {
+    const minimumVersion =
+      packageName === '@ankhorage/zora-chess'
+        ? '0.2.0'
+        : packageName === '@ankhorage/zora-tabletop'
+          ? '0.1.0'
+          : '0.0.0';
+    const requirement: OwnerRequirement = {
+      packageName,
+      minimumVersion,
+      specifier: `${packageName}/metadata`,
+      exports: ['ZORA_PLUGIN_METADATA'],
+    };
+    const plugin = await loadOwnerModule(targetDirectory, requirement);
+    const metadata = plugin.module.ZORA_PLUGIN_METADATA;
+    assertRecord(metadata, `${packageName} ZORA plugin metadata`);
+    loaded.push({ metadata, packageName, version: plugin.version });
+  }
+  return loaded;
+}
+
+function isZoraPluginPackage(packageName: string): boolean {
+  return packageName.startsWith('@ankhorage/zora-') && packageName !== '@ankhorage/zora';
+}
+
 /*** Load only Contracts for tooling that runs before another owner package has been built. */
 export async function loadContractsApi(targetDirectory = process.cwd()): Promise<ContractsApi> {
   const loaded = await loadOwnerModule(targetDirectory, OWNER_REQUIREMENTS.contracts);
@@ -661,6 +724,10 @@ function assertZoraThemeApi(value: Record<string, unknown>): asserts value is Zo
 
 /*** Narrow released ZORA metadata into only the fields the orchestration needs. */
 function assertZoraMetadataApi(value: Record<string, unknown>): asserts value is ZoraMetadataApi {
+  if (typeof value.composeZoraPluginMetadata !== 'function') {
+    throw new Error('composeZoraPluginMetadata must be a function.');
+  }
+  assertRecord(value.ZORA_CORE_PLUGIN_METADATA, 'ZORA_CORE_PLUGIN_METADATA');
   assertRecord(value.ZORA_COMPONENT_META, 'ZORA_COMPONENT_META');
   for (const [name, metadata] of Object.entries(value.ZORA_COMPONENT_META)) {
     assertComponentMetadata(metadata, name);
@@ -696,7 +763,9 @@ function assertEventMetadata(value: unknown, name: string): asserts value is Eve
   assertRecord(value, `ZORA event metadata ${name}`);
   assertNonEmptyString(value.eventType, `ZORA event metadata ${name}.eventType`);
   assertNonEmptyString(value.label, `ZORA event metadata ${name}.label`);
-  assertNonEmptyString(value.description, `ZORA event metadata ${name}.description`);
+  if (value.description !== undefined) {
+    assertNonEmptyString(value.description, `ZORA event metadata ${name}.description`);
+  }
 }
 
 /*** Validate one theme recipe metadata entry and its supported fields. */

package/dist/tools/skills/zoraDesignerOwnerFixtures.d.ts

@@ -0,0 +1,6 @@
+export declare function createThemeConfig(): Record<string, unknown>;
+export declare const TEMPLATES_FIXTURE_SOURCE: string;
+export declare const COLOR_THEORY_FIXTURE_SOURCE = "\nexport const COLOR_HARMONIES = ['monochromatic', 'complementary'];\nexport const COLOR_HARMONY_CATALOG = [\n  { id: 'monochromatic', label: 'Monochromatic', description: 'One hue.' },\n  { id: 'complementary', label: 'Complementary', description: 'Opposing hues.' },\n];\n";
+export declare const CONTRACTS_FIXTURE_SOURCE = "\nexport const APP_CATEGORIES = ['business_productivity'];\nexport const NAVIGATOR_TYPES = ['stack', 'tabs', 'drawer'];\n";
+export declare const ZORA_THEME_FIXTURE_SOURCE = "\nexport const compileZoraTheme = (themeConfig) => ({\n  themeConfig,\n  light: { surfaceTheme: { mode: 'light' }, diagnostics: [] },\n  dark: { surfaceTheme: { mode: 'dark' }, diagnostics: [] },\n  diagnostics: [],\n});\n";
+export declare const ZORA_METADATA_FIXTURE_SOURCE = "\nexport const ZORA_COMPONENT_META = {\n  Screen: {\n    name: 'Screen',\n    category: 'layout',\n    description: 'Screen layout root',\n    directManifestNode: true,\n    allowedChildren: ['View', 'Box', 'Text', 'MissingElement'],\n    props: {},\n  },\n  View: {\n    name: 'View',\n    category: 'layout',\n    directManifestNode: true,\n    allowedChildren: ['Text', 'Box'],\n    props: {},\n  },\n  Box: {\n    name: 'Box',\n    category: 'foundation',\n    directManifestNode: true,\n    allowedChildren: [],\n    props: {},\n  },\n  Text: {\n    name: 'Text',\n    category: 'component',\n    directManifestNode: true,\n    allowedChildren: [],\n    props: { text: { type: 'string' } },\n    events: {\n      press: {\n        eventType: 'text.press',\n        label: 'Press',\n        description: 'Text was pressed.',\n      },\n    },\n  },\n  MissingElement: {\n    name: 'MissingElement',\n    category: 'pattern',\n    directManifestNode: true,\n    allowedChildren: [],\n    manifestPolicy: { kind: 'unresolved-element', availability: 'draft-only', releaseGate: 'blocked' },\n    blueprint: { defaultProps: { requestedCapability: 'Unresolved', reason: 'No exact element.' } },\n    props: {\n      requestedCapability: { type: 'string' },\n      reason: { type: 'string' },\n      evidenceId: { type: 'string' },\n    },\n  },\n};\nexport const ZORA_CORE_PLUGIN_METADATA = {\n  packageName: '@ankhorage/zora',\n  componentMeta: ZORA_COMPONENT_META,\n  extensionHosts: ['Screen', 'View', 'Box'],\n};\nexport const composeZoraPluginMetadata = (plugins) => {\n  const componentMeta = {};\n  const extensionHosts = new Set();\n  for (const plugin of [...plugins].sort((left, right) => left.packageName.localeCompare(right.packageName))) {\n    Object.assign(componentMeta, plugin.componentMeta);\n    for (const host of plugin.extensionHosts ?? []) extensionHosts.add(host);\n  }\n  for (const plugin of plugins) {\n    for (const placement of plugin.placements ?? []) {\n      for (const parent of placement.parents) {\n        if (!extensionHosts.has(parent)) throw new Error('Invalid extension host');\n        componentMeta[parent] = {\n          ...componentMeta[parent],\n          allowedChildren: [...componentMeta[parent].allowedChildren, placement.child],\n        };\n      }\n    }\n  }\n  return { componentMeta };\n};\nexport const ZORA_THEME_RECIPE_META = {\n  Card: {\n    name: 'Card',\n    kind: 'component',\n    fields: { variant: { type: 'choice', options: ['filled', 'outlined'] } },\n  },\n};\n";

package/dist/tools/skills/zoraDesignerOwnerFixtures.js

@@ -0,0 +1,166 @@
+export function createThemeConfig() {
+    return {
+        id: 'evidence-theme',
+        name: 'Evidence Theme',
+        light: { primaryColor: '#2563EB', harmony: 'complementary' },
+        dark: { primaryColor: '#2563EB', harmony: 'complementary' },
+    };
+}
+export const TEMPLATES_FIXTURE_SOURCE = `
+export const CATEGORY_PRESETS = {
+  business_productivity: {
+    category: 'business_productivity',
+    label: 'Business',
+    recommendedPrimaryColors: ['#2563EB'],
+    recommendedHarmonies: ['complementary'],
+    tonePairs: { light: 'jewel-on-neutral-light', dark: 'pastel-on-neutral-dark' },
+    density: 'compact',
+  },
+};
+export const TONE_PAIR_CATALOG = [];
+export const resolveTonePair = () => null;
+export const resolveCategoryDesignPreset = (category, theme = {}) => ({ category, theme });
+const themeConfig = ${JSON.stringify(createThemeConfig())};
+export const compileCategoryDesign = (category) => ({
+  category,
+  themeConfig,
+  diagnostics: [],
+  computedTheme: {
+    themeConfig,
+    light: { surfaceTheme: { mode: 'light' }, diagnostics: [] },
+    dark: { surfaceTheme: { mode: 'dark' }, diagnostics: [] },
+    diagnostics: [],
+  },
+});
+export const composeCategoryAppManifest = (input) => ({
+  manifest: {
+    metadata: {
+      name: input.name ?? 'Generated App',
+      slug: input.slug ?? 'generated-app',
+      version: input.version ?? '1.0.0',
+      category: input.category,
+      themeId: 'evidence-theme',
+    },
+    themes: [themeConfig],
+    activeThemeId: 'evidence-theme',
+    infra: { modules: input.modules ?? [] },
+    navigator: input.navigator,
+    screens: input.screens,
+    settings: { localization: { defaultLocale: 'en', locales: ['en'] } },
+  },
+  diagnostics: [],
+  status: input.authoringState === 'release' ? 'ready' : 'blocked',
+  authoringState: input.authoringState,
+});
+export const validateTemplateManifest = (manifest) => ({
+  manifest,
+  diagnostics: [],
+  status: 'ready',
+  authoringState: 'release',
+});
+export const assertTemplateManifestReady = (composition) => composition.manifest;
+`;
+export const COLOR_THEORY_FIXTURE_SOURCE = `
+export const COLOR_HARMONIES = ['monochromatic', 'complementary'];
+export const COLOR_HARMONY_CATALOG = [
+  { id: 'monochromatic', label: 'Monochromatic', description: 'One hue.' },
+  { id: 'complementary', label: 'Complementary', description: 'Opposing hues.' },
+];
+`;
+export const CONTRACTS_FIXTURE_SOURCE = `
+export const APP_CATEGORIES = ['business_productivity'];
+export const NAVIGATOR_TYPES = ['stack', 'tabs', 'drawer'];
+`;
+export const ZORA_THEME_FIXTURE_SOURCE = `
+export const compileZoraTheme = (themeConfig) => ({
+  themeConfig,
+  light: { surfaceTheme: { mode: 'light' }, diagnostics: [] },
+  dark: { surfaceTheme: { mode: 'dark' }, diagnostics: [] },
+  diagnostics: [],
+});
+`;
+export const ZORA_METADATA_FIXTURE_SOURCE = `
+export const ZORA_COMPONENT_META = {
+  Screen: {
+    name: 'Screen',
+    category: 'layout',
+    description: 'Screen layout root',
+    directManifestNode: true,
+    allowedChildren: ['View', 'Box', 'Text', 'MissingElement'],
+    props: {},
+  },
+  View: {
+    name: 'View',
+    category: 'layout',
+    directManifestNode: true,
+    allowedChildren: ['Text', 'Box'],
+    props: {},
+  },
+  Box: {
+    name: 'Box',
+    category: 'foundation',
+    directManifestNode: true,
+    allowedChildren: [],
+    props: {},
+  },
+  Text: {
+    name: 'Text',
+    category: 'component',
+    directManifestNode: true,
+    allowedChildren: [],
+    props: { text: { type: 'string' } },
+    events: {
+      press: {
+        eventType: 'text.press',
+        label: 'Press',
+        description: 'Text was pressed.',
+      },
+    },
+  },
+  MissingElement: {
+    name: 'MissingElement',
+    category: 'pattern',
+    directManifestNode: true,
+    allowedChildren: [],
+    manifestPolicy: { kind: 'unresolved-element', availability: 'draft-only', releaseGate: 'blocked' },
+    blueprint: { defaultProps: { requestedCapability: 'Unresolved', reason: 'No exact element.' } },
+    props: {
+      requestedCapability: { type: 'string' },
+      reason: { type: 'string' },
+      evidenceId: { type: 'string' },
+    },
+  },
+};
+export const ZORA_CORE_PLUGIN_METADATA = {
+  packageName: '@ankhorage/zora',
+  componentMeta: ZORA_COMPONENT_META,
+  extensionHosts: ['Screen', 'View', 'Box'],
+};
+export const composeZoraPluginMetadata = (plugins) => {
+  const componentMeta = {};
+  const extensionHosts = new Set();
+  for (const plugin of [...plugins].sort((left, right) => left.packageName.localeCompare(right.packageName))) {
+    Object.assign(componentMeta, plugin.componentMeta);
+    for (const host of plugin.extensionHosts ?? []) extensionHosts.add(host);
+  }
+  for (const plugin of plugins) {
+    for (const placement of plugin.placements ?? []) {
+      for (const parent of placement.parents) {
+        if (!extensionHosts.has(parent)) throw new Error('Invalid extension host');
+        componentMeta[parent] = {
+          ...componentMeta[parent],
+          allowedChildren: [...componentMeta[parent].allowedChildren, placement.child],
+        };
+      }
+    }
+  }
+  return { componentMeta };
+};
+export const ZORA_THEME_RECIPE_META = {
+  Card: {
+    name: 'Card',
+    kind: 'component',
+    fields: { variant: { type: 'choice', options: ['filled', 'outlined'] } },
+  },
+};
+`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/devtools",
-  "version": "1.12.1",
+  "version": "1.14.0",
   "description": "Shared development tools and repository standards for Ankhorage",
   "license": "MIT",
   "homepage": "https://github.com/ankhorage/devtools#readme",
@@ -105,7 +105,7 @@
     "version-packages": "bun src/cli/bin/changeset.ts version"
   },
   "dependencies": {
-    "@ankhorage/utility": "^0.3.0",
+    "@ankhorage/utility": "^0.5.0",
     "@changesets/cli": "^3.0.2",
     "@eslint/compat": "^2.1.1",
     "@eslint/js": "^10.0.1",
@@ -114,7 +114,7 @@
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-prettier": "^5.5.6",
     "eslint-plugin-react": "^7.37.5",
-    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-react-hooks": "^7.0.0",
     "eslint-plugin-react-native": "^5.0.0",
     "eslint-plugin-security": "^4.0.1",
     "eslint-plugin-simple-import-sort": "^14.0.0",
@@ -126,8 +126,10 @@
   "devDependencies": {
     "@ankhorage/ankh": "^0.8.11",
     "@ankhorage/doctor": "0.10.8",
+    "@techstark/opencv-js": "^5.0.0-release.1",
     "@types/bun": "^1.4.1",
     "@types/node": "^26.4.1",
+    "sharp": "^0.35.4",
     "typescript": "~6.0.3"
   },
   "packageManager": "bun@1.4.2"