@ankhorage/devtools 1.10.2 → 1.10.3

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

@@ -77,6 +77,19 @@ When a required capability or source is unavailable, report that deliverable or
 blocked. Do not simulate an image, browser observation, or runtime proof. Clearly distinguish
 generated concept images from authoritative runtime captures.
 
+## Persist imagery before template release
+
+For a finalized template, retain three distinct image inventories: ordered generated concept
+screens, ordered authoritative runtime captures, and the original runtime images used by final
+ZORA `Image` nodes. A screenshot never substitutes for its underlying hero, card, avatar, or other
+runtime asset.
+
+When scaffolding in Templates, provide these inventories through the normal scaffold input. The
+scaffold copies durable source files into the template asset tree, registers each runtime image once
+in the canonical manifest media pool, validates the resulting bundle through released Templates,
+and writes the inventory to `zora-designer.md`. Read [workflow.md](references/workflow.md) for the
+input contract and release checks.
+
 ## Validate before handoff
 
 - Compile the category design and both theme modes through installed owner APIs.

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

@@ -31,6 +31,9 @@ is never invented:
 - `tokens`: current owner-computed token output, never copied token definitions;
 - `components`: metadata-backed recipe decisions and required states;
 - `screens`: ordered screen specifications and evidence relationships;
+- `imagery`: separate ordered `conceptSeries`, ordered `runtimeCaptures`, and `runtimeAssets` with
+  their durable template source path, generated-project target path where applicable, media ID,
+  dimensions, content type, byte size, origin, and provenance;
 - `validation`: scope, gates, application gate, owner/runtime drift, and blockers;
 - `auditInput`: criterion and release-gate assessments consumed by the canonical calculator;
 - `findings`, `risks`, `openDecisions`, and preserved `userNotes`.
@@ -79,7 +82,10 @@ score impact, risks, passed rules, and not-assessable criteria. Keep unavailable
 
 An image or series records each original source separately with dimensions and order. A URL records
 the capture viewport, theme mode, state, and reproduction. Concept images are labeled generated;
-runtime captures are labeled observed/measured and include their capture source.
+runtime captures are labeled observed/measured and include their capture source. Final runtime
+assets additionally record the manifest media ID, checked-in Template source path, and
+generated-project path. These are distinct inventories: a concept or runtime-capture screenshot
+does not prove the underlying screen image asset was retained.
 
 ## Output and persistence
 

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

@@ -88,7 +88,9 @@ 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.
+runtime capture only after running the manifest. Before final template release, retain the original
+files for every concept image, runtime capture, and final-screen runtime image with their measured
+dimensions, mode/state/order, origin, and provenance.
 
 ## 5. Audit a URL, image, or series
 
@@ -117,12 +119,24 @@ When the target repository is `@ankhorage/templates`, scaffold reviewed composit
 bun .agents/skills/zora-designer/scripts/scaffold-template.mjs scaffold-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.
+The scaffold input provides the ready manifest, category, template ID, label, description, target
+root, artifact input, and optional `imagery` inventory. The helper verifies the Templates repository
+and owner validation, creates a normal variant `manifest.ts`, `template.ts`, `assets.ts`, and
+`index.ts`, updates the category registry import and definition deterministically, and writes
+`zora-designer.md` with durable visual-asset inventory.
+
+Each `imagery.conceptSeries` and `imagery.runtimeCaptures` entry supplies `id`, `sourcePath`,
+`contentType`, measured `width`/`height`, `mode`, `state`, `order`, `origin`, and `provenance`.
+Each `imagery.runtimeAssets` entry supplies `mediaId`, `name`, `sourcePath`, `contentType`, measured
+`width`/`height`, `origin`, and `provenance`. The helper preserves source bytes under deterministic
+template evidence/runtime paths, derives collision-safe generated-project paths, creates the
+canonical bundled media entries, and validates the complete asset bundle through the released
+Templates API. Supply only durable local source files: `blob:` and `data:` URLs, symlinks, missing
+files, unsupported image formats, incomplete metadata, and duplicate identities are blocked.
+
+The helper 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
 

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

@@ -12,6 +12,7 @@ const HUMAN_SECTIONS = [
   'Layout, shape, elevation, and motion',
   'Component and interaction states',
   'Screen specifications',
+  'Visual assets',
   'Accessibility and validation',
   'Audit summary',
   'Findings and remediation',
@@ -111,6 +112,11 @@ export function serializeArtifact(input, audit) {
     tokens: input.tokens ?? {},
     components: input.components ?? { stateRequirements: [], recipeDecisions: {} },
     screens: input.screens ?? [],
+    imagery: input.imagery ?? {
+      conceptSeries: [],
+      runtimeCaptures: [],
+      runtimeAssets: [],
+    },
     validation: input.validation ?? {
       scope: documentKind === 'audit' ? 'audit' : 'configuration',
       status: 'not-run',

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

@@ -5,7 +5,7 @@ import { dirname, join, parse, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 
 const OWNER_RELEASES = {
-  templates: { packageName: '@ankhorage/templates', minimumVersion: '8.0.0' },
+  templates: { packageName: '@ankhorage/templates', minimumVersion: '9.0.0' },
   zora: { packageName: '@ankhorage/zora', minimumVersion: '4.0.0' },
 };
 
@@ -22,6 +22,7 @@ const OWNER_REQUIREMENTS = {
       'composeCategoryAppManifest',
       'validateTemplateManifest',
       'assertTemplateManifestReady',
+      'createStarterTemplateArtifact',
     ],
   },
   zoraTheme: {

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

@@ -4,7 +4,9 @@ import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
 import { join, relative, resolve, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
 
+import { serializeArtifact } from './audit.mjs';
 import { loadOwnerApis } from './owner-api.mjs';
+import { prepareTemplateImagery, writeTemplateImagery } from './template-imagery.mjs';
 
 /*** Validate and scaffold one ready authored manifest into the normal Templates variant layout. */
 export async function scaffoldTemplate(input) {
@@ -54,38 +56,57 @@ export async function scaffoldTemplate(input) {
     );
   }
 
+  const imagery = await prepareTemplateImagery(input, targetDirectory, manifest, owners);
   const registryPath = join(categoryDirectory, 'index.ts');
   const registrySource = await readFile(registryPath, 'utf8');
   const symbol = toPascalCase(input.templateId);
   const factoryBase = symbol.endsWith('Starter') ? symbol.slice(0, -'Starter'.length) : symbol;
   const factoryName = `create${factoryBase}StarterTemplate`;
   const manifestName = `AUTHORED_${toConstantCase(input.templateId)}_MANIFEST`;
+  const assetsName = `AUTHORED_${toConstantCase(input.templateId)}_ASSETS`;
   const registrySourceUpdated = updateCategoryRegistry(registrySource, {
     templateId: input.templateId,
     label: input.label,
     description: input.description,
     factoryName,
+    assetsName,
   });
-  const files = createTemplateFiles({ manifest, manifestName, factoryName });
+  const files = createTemplateFiles({
+    manifest: imagery.artifact.manifest,
+    manifestName,
+    factoryName,
+    assets: imagery.artifact.assets,
+    assetsName,
+  });
+  const artifactPath = resolve(targetDirectory, input.artifactPath ?? 'zora-designer.md');
+  assertInside(targetDirectory, artifactPath);
+  const artifact = serializeArtifact({ ...(input.artifact ?? {}), imagery: imagery.inventory });
 
   await mkdir(variantDirectory, { recursive: true });
   for (const [fileName, contents] of Object.entries(files)) {
     await writeFile(join(variantDirectory, fileName), contents);
   }
+  await writeTemplateImagery(imagery.files, targetDirectory, writeFile, mkdir);
   await writeFile(registryPath, registrySourceUpdated);
+  await writeFile(artifactPath, artifact);
 
   return {
     targetDirectory,
     registryPath: relative(targetDirectory, registryPath),
-    createdFiles: Object.keys(files).map((fileName) =>
-      relative(targetDirectory, join(variantDirectory, fileName)),
-    ),
+    createdFiles: [
+      ...Object.keys(files).map((fileName) =>
+        relative(targetDirectory, join(variantDirectory, fileName)),
+      ),
+      ...imagery.files.map((file) => file.destinationPath),
+      relative(targetDirectory, artifactPath),
+    ].sort(),
     factoryName,
+    imagery: imagery.inventory,
   };
 }
 
 /*** Create normal manifest, factory, and entrypoint source for one authored starter variant. */
-function createTemplateFiles({ manifest, manifestName, factoryName }) {
+function createTemplateFiles({ manifest, manifestName, factoryName, assets, assetsName }) {
   const manifestSource = `import type { AppManifest } from '@ankhorage/contracts';
 
 export const ${manifestName} = ${JSON.stringify(manifest, null, 2)} satisfies AppManifest;
@@ -114,8 +135,13 @@ export function ${factoryName}(seed: TemplateSeed): AppManifest {
     activeThemeId: theme.id,
   };
 }
+`;
+  const assetSource = `import type { StarterTemplateAsset } from '../../../starter.assets';
+
+export const ${assetsName} = ${JSON.stringify(assets, null, 2)} satisfies readonly StarterTemplateAsset[];
 `;
   return {
+    'assets.ts': assetSource,
     'index.ts': `export { ${factoryName} } from './template';\n`,
     'manifest.ts': manifestSource,
     'template.ts': templateSource,
@@ -125,7 +151,12 @@ export function ${factoryName}(seed: TemplateSeed): AppManifest {
 /*** Add one stable import and definition to an existing category registry. */
 function updateCategoryRegistry(source, definition) {
   const importLine = `import { ${definition.factoryName} } from './${definition.templateId}';`;
-  if (source.includes(`id: '${definition.templateId}'`) || source.includes(importLine)) {
+  const assetsImportLine = `import { ${definition.assetsName} } from './${definition.templateId}/assets';`;
+  if (
+    source.includes(`id: '${definition.templateId}'`) ||
+    source.includes(importLine) ||
+    source.includes(assetsImportLine)
+  ) {
     throw new Error(`Template is already registered: ${definition.templateId}`);
   }
   const exportMarker = '\nexport const ';
@@ -137,6 +168,7 @@ function updateCategoryRegistry(source, definition) {
   const relativeImports = [
     ...prefixLines.filter((line) => /^import .* from '\.\//u.test(line)),
     importLine,
+    assetsImportLine,
   ].sort((left, right) => left.localeCompare(right));
   const preservedPrefix = prefixLines.filter((line) => !/^import .* from '\.\//u.test(line));
   const withImport = `${[...preservedPrefix, ...relativeImports].join('\n')}\n${source.slice(exportIndex + 1)}`;
@@ -150,6 +182,7 @@ function updateCategoryRegistry(source, definition) {
     label: '${escapeSingleQuoted(definition.label)}',
     description: '${escapeSingleQuoted(definition.description)}',
     create: ${definition.factoryName},
+    assets: ${definition.assetsName},
   },
 `;
   return `${withImport.slice(0, closeIndex)}${entry}${withImport.slice(closeIndex)}`;

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

@@ -0,0 +1,361 @@
+import { createHash } from 'node:crypto';
+import { lstat, readFile } from 'node:fs/promises';
+import { dirname, relative, resolve, sep } from 'node:path';
+
+const IMAGE_CONTENT_TYPES = {
+  'image/avif': '.avif',
+  'image/gif': '.gif',
+  'image/jpeg': '.jpg',
+  'image/png': '.png',
+  'image/svg+xml': '.svg',
+  'image/webp': '.webp',
+};
+
+/*** Prepare immutable template evidence and runtime images through the released Templates asset API. */
+export async function prepareTemplateImagery(input, targetDirectory, manifest, owners) {
+  const imagery = input.imagery ?? {};
+  assertRecord(imagery, 'imagery');
+  const root = `assets/templates/${input.category.replaceAll('_', '-')}/${input.templateId}`;
+  const conceptSeries = await prepareEvidenceSeries(
+    imagery.conceptSeries ?? [],
+    'concept series',
+    `${root}/evidence/concepts`,
+  );
+  const runtimeCaptures = await prepareEvidenceSeries(
+    imagery.runtimeCaptures ?? [],
+    'runtime captures',
+    `${root}/evidence/runtime-captures`,
+  );
+  const runtimeAssets = await prepareRuntimeAssets(
+    imagery.runtimeAssets ?? [],
+    `${root}/runtime`,
+    `assets/media/${input.templateId}`,
+  );
+  const resolvedManifest = registerRuntimeAssets(manifest, runtimeAssets);
+  assertRuntimeAssetsAreReferenced(resolvedManifest, runtimeAssets);
+  const composition = owners.templates.validateTemplateManifest(resolvedManifest, 'release');
+  if (composition.status !== 'ready') {
+    throw new Error(
+      `Manifest is not release-ready after imagery registration: ${composition.diagnostics.map((item) => item.message).join('; ')}`,
+    );
+  }
+  const readyManifest = owners.templates.assertTemplateManifestReady(composition);
+  const artifact = owners.templates.createStarterTemplateArtifact(
+    readyManifest,
+    runtimeAssets.map((asset) => asset.descriptor),
+  );
+  const files = [...conceptSeries, ...runtimeCaptures, ...runtimeAssets].sort((left, right) =>
+    left.destinationPath.localeCompare(right.destinationPath),
+  );
+  assertUniqueDestinations(files);
+
+  return {
+    artifact,
+    files,
+    inventory: {
+      conceptSeries: conceptSeries.map(toEvidenceInventory),
+      runtimeCaptures: runtimeCaptures.map(toEvidenceInventory),
+      runtimeAssets: runtimeAssets.map(toRuntimeAssetInventory),
+    },
+  };
+}
+
+/*** Write only prevalidated copied image bytes into their canonical checked-in Templates paths. */
+export async function writeTemplateImagery(files, targetDirectory, writeFile, mkdir) {
+  for (const file of files) {
+    const destination = resolve(targetDirectory, file.destinationPath);
+    assertInside(targetDirectory, destination, 'Template imagery destination');
+    await assertDestinationIsMissing(destination, file.destinationPath);
+    await mkdir(dirname(destination), { recursive: true });
+    await writeFile(destination, file.contents);
+  }
+}
+
+/*** Reject accidental replacement of an existing checked-in image outside the new variant boundary. */
+async function assertDestinationIsMissing(destination, relativeDestination) {
+  try {
+    await lstat(destination);
+  } catch (error) {
+    if (isNotFoundError(error)) return;
+    throw error;
+  }
+  throw new Error(`Template imagery destination already exists: ${relativeDestination}`);
+}
+
+/*** Prepare one ordered concept or runtime-capture series without confusing evidence for runtime media. */
+async function prepareEvidenceSeries(items, label, destinationDirectory) {
+  if (!Array.isArray(items)) throw new Error(`${label} must be an array.`);
+  const prepared = await Promise.all(
+    items.map(async (item) => {
+      assertRecord(item, `${label} item`);
+      const id = readNonEmptyString(item.id, `${label} item id`);
+      const order = readOrder(item.order, `${label} item ${id} order`);
+      const mode = readNonEmptyString(item.mode, `${label} item ${id} mode`);
+      const state = readNonEmptyString(item.state, `${label} item ${id} state`);
+      const image = await readSourceImage(item, `${label} item ${id}`);
+      return {
+        ...image,
+        id,
+        order,
+        mode,
+        state,
+        destinationPath: `${destinationDirectory}/${String(order).padStart(3, '0')}-${safeStem(id)}${image.extension}`,
+      };
+    }),
+  );
+  assertUniqueIds(prepared, label);
+  assertUniqueOrders(prepared, label);
+  return prepared.sort(
+    (left, right) => left.order - right.order || left.id.localeCompare(right.id),
+  );
+}
+
+/*** Prepare a runtime image, deriving both its packaged source and generated-project target paths. */
+async function prepareRuntimeAssets(items, sourceDirectory, targetDirectory) {
+  if (!Array.isArray(items)) throw new Error('runtimeAssets must be an array.');
+  const prepared = await Promise.all(
+    items.map(async (item) => {
+      assertRecord(item, 'runtime asset');
+      const mediaId = readNonEmptyString(item.mediaId, 'runtime asset mediaId');
+      const name = readNonEmptyString(item.name, `runtime asset ${mediaId} name`);
+      const image = await readSourceImage(item, `runtime asset ${mediaId}`);
+      const stem = safeStem(mediaId);
+      const sourcePath = `${sourceDirectory}/${stem}${image.extension}`;
+      const targetPath = `${targetDirectory}/${stem}${image.extension}`;
+      return {
+        ...image,
+        mediaId,
+        name,
+        destinationPath: sourcePath,
+        descriptor: {
+          sourcePath,
+          targetPath,
+          contentType: image.contentType,
+          sizeBytes: image.sizeBytes,
+          sha256: image.sha256,
+        },
+      };
+    }),
+  );
+  assertUniqueIds(prepared, 'runtime assets', 'mediaId');
+  return prepared.sort((left, right) => left.mediaId.localeCompare(right.mediaId));
+}
+
+/*** Read immutable image bytes and the complete provenance required for a durable template record. */
+async function readSourceImage(item, label) {
+  const sourcePath = readNonEmptyString(item.sourcePath, `${label} sourcePath`);
+  if (sourcePath.startsWith('blob:') || sourcePath.startsWith('data:')) {
+    throw new Error(`${label} sourcePath must name a durable image file, not a transient URL.`);
+  }
+  const absoluteSourcePath = resolve(sourcePath);
+  const stats = await lstat(absoluteSourcePath);
+  if (!stats.isFile() || stats.isSymbolicLink()) {
+    throw new Error(`${label} sourcePath must be a regular non-symlink file.`);
+  }
+  const contentType = readContentType(item.contentType, label);
+  const width = readPositiveInteger(item.width, `${label} width`);
+  const height = readPositiveInteger(item.height, `${label} height`);
+  const origin = readNonEmptyString(item.origin, `${label} origin`);
+  assertRecord(item.provenance, `${label} provenance`);
+  const contents = await readFile(absoluteSourcePath);
+  if (contents.byteLength === 0) throw new Error(`${label} sourcePath must not be empty.`);
+  return {
+    contents,
+    contentType,
+    extension: IMAGE_CONTENT_TYPES[contentType],
+    height,
+    origin,
+    provenance: item.provenance,
+    sha256: createHash('sha256').update(contents).digest('hex'),
+    sizeBytes: contents.byteLength,
+    width,
+  };
+}
+
+/*** Register each checked-in runtime file once in the canonical manifest media pool. */
+function registerRuntimeAssets(manifest, runtimeAssets) {
+  const resolvedManifest = structuredClone(manifest);
+  const media = resolvedManifest.media ?? { assets: {} };
+  const assets = media.assets ?? {};
+  for (const asset of runtimeAssets) {
+    if (assets[asset.mediaId] !== undefined) {
+      throw new Error(`Manifest media already defines runtime asset: ${asset.mediaId}`);
+    }
+    assets[asset.mediaId] = {
+      id: asset.mediaId,
+      name: asset.name,
+      kind: 'image',
+      source: { kind: 'bundled', path: asset.descriptor.targetPath },
+      contentType: asset.contentType,
+      metadata: {
+        sizeBytes: asset.sizeBytes,
+        width: asset.width,
+        height: asset.height,
+      },
+    };
+  }
+  resolvedManifest.media = { ...media, assets };
+  return resolvedManifest;
+}
+
+/*** Require every final runtime image asset to serve an exact canonical ZORA Image media reference. */
+function assertRuntimeAssetsAreReferenced(manifest, runtimeAssets) {
+  const imageMediaIds = new Set();
+  for (const screen of Object.values(manifest.screens ?? {})) {
+    collectImageMediaIds(screen.root, imageMediaIds);
+  }
+  for (const runtimeAsset of runtimeAssets) {
+    if (!imageMediaIds.has(runtimeAsset.mediaId)) {
+      throw new Error(
+        `Runtime asset is not referenced by a ZORA Image mediaId: ${runtimeAsset.mediaId}`,
+      );
+    }
+  }
+}
+
+/*** Collect only explicit Image source media references from one recursively composed manifest tree. */
+function collectImageMediaIds(node, imageMediaIds) {
+  if (!isRecord(node)) return;
+  if (node.type === 'Image') {
+    const mediaId = node.props?.source?.mediaId;
+    if (typeof mediaId !== 'string' || mediaId === '') {
+      throw new Error('Every final ZORA Image must use one canonical source.mediaId reference.');
+    }
+    imageMediaIds.add(mediaId);
+  }
+  for (const child of Array.isArray(node.children) ? node.children : []) {
+    collectImageMediaIds(child, imageMediaIds);
+  }
+}
+
+/*** Project evidence records into a portable artifact inventory without temporary input paths. */
+function toEvidenceInventory(item) {
+  return {
+    id: item.id,
+    path: item.destinationPath,
+    order: item.order,
+    mode: item.mode,
+    state: item.state,
+    contentType: item.contentType,
+    sizeBytes: item.sizeBytes,
+    width: item.width,
+    height: item.height,
+    origin: item.origin,
+    provenance: item.provenance,
+  };
+}
+
+/*** Project a runtime image into artifact evidence and its canonical manifest/project references. */
+function toRuntimeAssetInventory(item) {
+  return {
+    mediaId: item.mediaId,
+    sourcePath: item.descriptor.sourcePath,
+    targetPath: item.descriptor.targetPath,
+    contentType: item.contentType,
+    sizeBytes: item.sizeBytes,
+    width: item.width,
+    height: item.height,
+    origin: item.origin,
+    provenance: item.provenance,
+  };
+}
+
+/*** Reject duplicate final destinations before any target repository mutation begins. */
+function assertUniqueDestinations(files) {
+  const destinations = new Set();
+  for (const file of files) {
+    if (destinations.has(file.destinationPath)) {
+      throw new Error(`Template imagery destination is duplicated: ${file.destinationPath}`);
+    }
+    destinations.add(file.destinationPath);
+  }
+}
+
+/*** Reject duplicate source identities while preserving explicit property-specific diagnostics. */
+function assertUniqueIds(items, label, field = 'id') {
+  const ids = new Set();
+  for (const item of items) {
+    const id = item[field];
+    if (ids.has(id)) throw new Error(`${label} has a duplicate ${field}: ${id}`);
+    ids.add(id);
+  }
+}
+
+/*** Require a meaningful sequence position for each durable evidence image. */
+function assertUniqueOrders(items, label) {
+  const orders = new Set();
+  for (const item of items) {
+    if (orders.has(item.order)) throw new Error(`${label} has a duplicate order: ${item.order}`);
+    orders.add(item.order);
+  }
+}
+
+/*** Turn arbitrary durable identities into stable collision-resistant portable file stems. */
+function safeStem(value) {
+  const normalized = value
+    .normalize('NFKD')
+    .replace(/[^a-zA-Z0-9]+/gu, '-')
+    .replace(/^-+|-+$/gu, '')
+    .toLowerCase();
+  const readable = normalized === '' ? 'image' : normalized;
+  return `${readable}-${createHash('sha256').update(value).digest('hex').slice(0, 12)}`;
+}
+
+/*** Require one supported image content type and rely on that owner-compatible extension mapping. */
+function readContentType(value, label) {
+  if (typeof value !== 'string' || !(value in IMAGE_CONTENT_TYPES)) {
+    throw new Error(`${label} contentType must be one supported bundled image content type.`);
+  }
+  return value;
+}
+
+/*** Require an explicit non-empty string rather than inferring immutable artifact metadata. */
+function readNonEmptyString(value, label) {
+  if (typeof value !== 'string' || value.trim() === '')
+    throw new Error(`${label} must be non-empty.`);
+  return value;
+}
+
+/*** Require real measured dimensions and an ordered series index. */
+function readPositiveInteger(value, label) {
+  if (!Number.isSafeInteger(value) || value <= 0)
+    throw new Error(`${label} must be a positive integer.`);
+  return value;
+}
+
+/*** Read an explicit nonnegative evidence-series position. */
+function readOrder(value, label) {
+  if (!Number.isSafeInteger(value) || value < 0)
+    throw new Error(`${label} must be a nonnegative integer.`);
+  return value;
+}
+
+/*** Reject source and output path escapes at the filesystem handoff boundary. */
+function assertInside(parentDirectory, childPath, label) {
+  const relativePath = relative(parentDirectory, childPath);
+  if (
+    relativePath === '' ||
+    relativePath === '..' ||
+    relativePath.startsWith(`..${sep}`) ||
+    relativePath.includes(`${sep}..${sep}`)
+  ) {
+    throw new Error(`${label} escapes its owner directory: ${childPath}`);
+  }
+}
+
+/*** Narrow an unknown input value to one non-array record. */
+function assertRecord(value, label) {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new Error(`${label} must be an object.`);
+  }
+}
+
+/*** Narrow filesystem failures to the missing-path condition needed for no-overwrite protection. */
+function isNotFoundError(error) {
+  return error instanceof Error && 'code' in error && error.code === 'ENOENT';
+}
+
+/*** Narrow unknown manifest data to object-shaped node records. */
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/tools/skills/zoraDesignerImagery.fixtures.d.ts

@@ -0,0 +1,14 @@
+/*** Remove every temporary Templates fixture created by imagery behavior tests. */
+export declare function cleanupTemplatesFixtures(): Promise<void>;
+/*** Set up the minimum released owner surface required by the packaged skill script. */
+export declare function createTemplatesFixture(): Promise<string>;
+/*** Create one complete input whose manifest is ready before imagery registration. */
+export declare function createScaffoldInput(targetDirectory: string, templateId: string): Record<string, unknown>;
+/*** Write deterministic source images that the skill must retain inside the target template. */
+export declare function writeFixtureImages(target: string): Promise<Record<'capture' | 'concept' | 'hero', string>>;
+/*** Create one complete ordered evidence record for a durable fixture image. */
+export declare function imageEvidence(id: string, sourcePath: string, contentType: string, width: number, height: number, mode: string, state: string, order: number): Record<string, unknown>;
+/*** Write deterministic JSON input to the temporary target repository. */
+export declare function writeJson(path: string, value: unknown): Promise<void>;
+/*** Return the one category registry path owned by this focused fixture. */
+export declare function categoryPath(target: string): string;

package/dist/tools/skills/zoraDesignerImagery.fixtures.js

@@ -0,0 +1,141 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const temporaryDirectories = [];
+/*** Remove every temporary Templates fixture created by imagery behavior tests. */
+export async function cleanupTemplatesFixtures() {
+    await Promise.all(temporaryDirectories
+        .splice(0)
+        .map((directory) => rm(directory, { force: true, recursive: true })));
+}
+/*** Set up the minimum released owner surface required by the packaged skill script. */
+export async function createTemplatesFixture() {
+    const target = await mkdtemp('/tmp/devtools-zora-imagery-');
+    temporaryDirectories.push(target);
+    await writeJson(join(target, 'package.json'), {
+        name: '@ankhorage/templates',
+        version: '9.0.0',
+        type: 'module',
+        exports: { '.': './index.js', './package.json': './package.json' },
+    });
+    await writeFile(join(target, 'index.js'), TEMPLATES_FIXTURE_SOURCE);
+    await writeFixturePackage(target, '@ankhorage/zora', '4.0.0', {
+        './theme': './theme.js',
+        './metadata': './metadata.js',
+        './package.json': './package.json',
+    });
+    const zoraDirectory = join(target, 'node_modules/@ankhorage/zora');
+    await writeFile(join(zoraDirectory, 'theme.js'), 'export const compileZoraTheme = () => ({});\n');
+    await writeFile(join(zoraDirectory, 'metadata.js'), 'export const ZORA_COMPONENT_META = {}; export const ZORA_THEME_RECIPE_META = {};\n');
+    await mkdir(categoryPath(target), { recursive: true });
+    await writeFile(join(categoryPath(target), 'index.ts'), CATEGORY_REGISTRY_SOURCE);
+    return target;
+}
+/*** Create one complete input whose manifest is ready before imagery registration. */
+export function createScaffoldInput(targetDirectory, templateId) {
+    return {
+        targetDirectory,
+        category: 'business_productivity',
+        templateId,
+        label: 'Evidence Board',
+        description: 'A metadata-backed evidence review starter.',
+        artifact: { status: 'resolved', source: { mode: 'template', inputs: [], evidence: [] } },
+        manifest: createManifest(),
+    };
+}
+/*** Write deterministic source images that the skill must retain inside the target template. */
+export async function writeFixtureImages(target) {
+    const concept = join(target, 'concept.png');
+    const capture = join(target, 'capture.png');
+    const hero = join(target, 'hero.svg');
+    await Promise.all([
+        writeFile(concept, 'concept-image'),
+        writeFile(capture, 'runtime-capture'),
+        writeFile(hero, '<svg xmlns="http://www.w3.org/2000/svg"/>'),
+    ]);
+    return { concept, capture, hero };
+}
+/*** Create one complete ordered evidence record for a durable fixture image. */
+export function imageEvidence(id, sourcePath, contentType, width, height, mode, state, order) {
+    return {
+        id,
+        sourcePath,
+        contentType,
+        width,
+        height,
+        mode,
+        state,
+        order,
+        origin: 'generated',
+        provenance: { tool: 'fixture' },
+    };
+}
+/*** Write deterministic JSON input to the temporary target repository. */
+export async function writeJson(path, value) {
+    await writeFile(path, `${JSON.stringify(value, null, 2)}\n`);
+}
+/*** Return the one category registry path owned by this focused fixture. */
+export function categoryPath(target) {
+    return join(target, 'src/templates/starter/categories/business-productivity');
+}
+/*** Install one minimal public ESM package fixture under the target repository. */
+async function writeFixturePackage(target, packageName, version, exports) {
+    const directory = join(target, 'node_modules', packageName);
+    await mkdir(directory, { recursive: true });
+    await writeJson(join(directory, 'package.json'), {
+        name: packageName,
+        version,
+        type: 'module',
+        exports,
+    });
+}
+/*** Create the released-ready base manifest used by the owner fixture. */
+function createManifest() {
+    const theme = {
+        id: 'evidence-theme',
+        name: 'Evidence Theme',
+        light: { primaryColor: '#2563EB', harmony: 'complementary' },
+        dark: { primaryColor: '#2563EB', harmony: 'complementary' },
+    };
+    return {
+        metadata: {
+            name: 'Evidence Board',
+            slug: 'evidence-board',
+            version: '1.0.0',
+            category: 'business_productivity',
+            themeId: theme.id,
+        },
+        themes: [theme],
+        activeThemeId: theme.id,
+        infra: { modules: [] },
+        navigator: { type: 'stack', routes: [{ name: 'index', screenId: 'home' }] },
+        screens: {
+            home: {
+                id: 'home',
+                name: 'Home',
+                root: {
+                    id: 'home-root',
+                    type: 'View',
+                    children: [
+                        { id: 'hero-image', type: 'Image', props: { source: { mediaId: 'hero-image' } } },
+                    ],
+                },
+            },
+        },
+        settings: { localization: { defaultLocale: 'en', locales: ['en'] } },
+    };
+}
+const CATEGORY_REGISTRY_SOURCE = `import type { CategoryStarterTemplateDefinition } from '../../starter.types';
+
+export const businessProductivityStarterTemplates = [] satisfies readonly CategoryStarterTemplateDefinition[];
+`;
+const TEMPLATES_FIXTURE_SOURCE = `
+export const CATEGORY_PRESETS = {};
+export const TONE_PAIR_CATALOG = [];
+export const resolveTonePair = () => null;
+export const resolveCategoryDesignPreset = () => ({});
+export const compileCategoryDesign = () => ({});
+export const composeCategoryAppManifest = () => ({});
+export const validateTemplateManifest = (manifest) => ({ manifest, diagnostics: [], status: 'ready' });
+export const assertTemplateManifestReady = (composition) => composition.manifest;
+export const createStarterTemplateArtifact = (manifest, assets) => ({ manifest, assets });
+`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/devtools",
-  "version": "1.10.2",
+  "version": "1.10.3",
   "description": "Shared development tools and repository standards for Ankhorage",
   "license": "MIT",
   "homepage": "https://github.com/ankhorage/devtools#readme",