@ankhorage/devtools 1.10.15 → 1.11.0

package/README.md

@@ -296,9 +296,9 @@ The canonical Bun policy is defined once in devtools and consumed by both packag
 <!-- devtools-bun-policy:start -->
 
 ```text
-Bun runtime       1.4.0
-packageManager    bun@1.4.0
-@types/bun        ^1.4.0
+Bun runtime       1.4.1
+packageManager    bun@1.4.1
+@types/bun        ^1.4.1
 ```
 
 <!-- devtools-bun-policy:end -->

package/dist/policy/bunRuntimePolicy.d.ts

@@ -1,7 +1,7 @@
 export declare const bunRuntimePolicy: {
-    readonly packageManager: "bun@1.4.0";
-    readonly typesRange: "^1.4.0";
-    readonly version: "1.4.0";
+    readonly packageManager: "bun@1.4.1";
+    readonly typesRange: "^1.4.1";
+    readonly version: "1.4.1";
 };
 /**
  * Canonical Node LTS baseline for Node-based Ankhorage tooling and CI execution.

package/dist/policy/bunRuntimePolicy.js

@@ -4,7 +4,7 @@
  * Import these from `@ankhorage/devtools/policy` when another package needs to inspect
  * the managed Bun or Node baseline without defining an independent version authority.
  */
-const BUN_VERSION = '1.4.0';
+const BUN_VERSION = '1.4.1';
 export const bunRuntimePolicy = {
     packageManager: `bun@${BUN_VERSION}`,
     typesRange: `^${BUN_VERSION}`,

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

@@ -0,0 +1,64 @@
+export declare const ICON_SVG = "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><path d=\"M2 2h20v20H2z\"/></svg>";
+export declare const IMAGE_PNG: Buffer<ArrayBuffer>;
+/*** Create manifest configuration shared by the asset scaffolding fixture. */
+export declare function createFixtureManifest(theme: Record<string, unknown>): Record<string, unknown>;
+/*** Create separate screen evidence, image content and SVG with runtime references. */
+export declare function createAssetFixture(root: string): Promise<{
+    bundle: {
+        assets: {
+            mediaId: string;
+            role: string;
+            sourcePath: string;
+            targetPath: string;
+            contentType: string;
+            usages: string[];
+        }[];
+        screens: {
+            sourcePath: string;
+            targetPath: string;
+        }[];
+    };
+    bundlePath: string;
+    manifest: {
+        media: {
+            assets: {
+                [k: string]: {
+                    id: string;
+                    kind: string;
+                    source: {
+                        kind: string;
+                        path: string;
+                    };
+                    contentType: string;
+                };
+            };
+        };
+        navigator: {
+            type: string;
+            routes: {
+                name: string;
+                screenId: string;
+                icon: {
+                    source: {
+                        mediaId: string;
+                    };
+                };
+            }[];
+        };
+        screens: {
+            home: {
+                id: string;
+                name: string;
+                root: {
+                    id: string;
+                    type: string;
+                    props: {
+                        source: {
+                            mediaId: string;
+                        };
+                    };
+                };
+            };
+        };
+    };
+}>;

package/dist/tools/skills/assetTestFixture.js

@@ -0,0 +1,81 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export const ICON_SVG = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M2 2h20v20H2z"/></svg>';
+export const IMAGE_PNG = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+a7x8AAAAASUVORK5CYII=', 'base64');
+/*** Create manifest configuration shared by the asset scaffolding fixture. */
+export function createFixtureManifest(theme) {
+    return {
+        metadata: {
+            name: 'Evidence Board',
+            slug: 'evidence-board',
+            version: '1.0.0',
+            category: 'business_productivity',
+            themeId: 'evidence-theme',
+        },
+        themes: [theme],
+        activeThemeId: 'evidence-theme',
+        infra: { modules: [] },
+        settings: { localization: { defaultLocale: 'en', locales: ['en'] } },
+    };
+}
+/*** Create separate screen evidence, image content and SVG with runtime references. */
+export async function createAssetFixture(root) {
+    await mkdir(join(root, 'assets/images/svg'), { recursive: true });
+    await mkdir(join(root, 'assets/screens'), { recursive: true });
+    await writeFile(join(root, 'assets/images/svg/book.svg'), ICON_SVG);
+    await writeFile(join(root, 'assets/images/cover.png'), IMAGE_PNG);
+    await writeFile(join(root, 'assets/screens/home.png'), IMAGE_PNG);
+    const assets = createAssetEntries();
+    const bundle = {
+        assets,
+        screens: [{ sourcePath: 'assets/screens/home.png', targetPath: 'assets/screens/home.png' }],
+    };
+    const bundlePath = join(root, 'design-assets.json');
+    await writeFile(bundlePath, JSON.stringify(bundle));
+    const manifest = {
+        media: {
+            assets: Object.fromEntries(assets.map((asset) => [
+                asset.mediaId,
+                {
+                    id: asset.mediaId,
+                    kind: 'image',
+                    source: { kind: 'bundled', path: asset.targetPath },
+                    contentType: asset.contentType,
+                },
+            ])),
+        },
+        navigator: {
+            type: 'stack',
+            routes: [{ name: 'home', screenId: 'home', icon: { source: { mediaId: 'book' } } }],
+        },
+        screens: {
+            home: {
+                id: 'home',
+                name: 'Home',
+                root: { id: 'cover-image', type: 'Image', props: { source: { mediaId: 'cover' } } },
+            },
+        },
+    };
+    return { bundle, bundlePath, manifest };
+}
+/*** Describe the reusable icon and image inputs independently of filesystem setup. */
+function createAssetEntries() {
+    return [
+        {
+            mediaId: 'book',
+            role: 'icon',
+            sourcePath: 'assets/images/svg/book.svg',
+            targetPath: 'assets/images/svg/book.svg',
+            contentType: 'image/svg+xml',
+            usages: ['/navigator/routes/0/icon/source'],
+        },
+        {
+            mediaId: 'cover',
+            role: 'image',
+            sourcePath: 'assets/images/cover.png',
+            targetPath: 'assets/images/cover.png',
+            contentType: 'image/png',
+            usages: ['/screens/home/root/props/source'],
+        },
+    ];
+}

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

@@ -59,6 +59,11 @@ work. Release validation still decides whether the complete manifest is shippabl
 
 ## Template output
 
+For every creation mode, read [runtime-assets.md](references/runtime-assets.md). Inventory icons
+and images during configuration, produce separate reusable files with the screens, and carry the
+same checked asset bundle into template generation. Direct template requests prepare that bundle
+before scaffolding as well.
+
 A Templates repository template is exactly one portable unit:
 
 ```text
@@ -67,11 +72,13 @@ src/templates/categories/{appCategory}/{slug}/
   assets/
     screens/
     images/
+      svg/
 ```
 
 `createAppManifest.ts` default-exports a function returning the complete `AppManifest`.
 `assets/screens/` contains design evidence only. Runtime media uses real application image regions
-under `assets/images/`; rebuild text, controls, icons, surfaces, and layout with ZORA.
+under `assets/images/`, with vector icons under `assets/images/svg/`. Rebuild text, controls,
+surfaces and layout with ZORA; use `Icon source` and `Image` for the corresponding asset references.
 
 Scaffold only a reviewed, release-valid manifest:
 
@@ -79,7 +86,8 @@ Scaffold only a reviewed, release-valid manifest:
 bun .agents/skills/zora-designer/scripts/scaffold-template.ts scaffold-input.json
 ```
 
-The helper creates the template directory and regenerates discovery from the filesystem. Do not add
+The helper requires `assetBundlePath`, checks files and manifest references before output, copies
+runtime assets and screen evidence, and regenerates discovery from the filesystem. Do not add
 category registries, seed definitions, fallback templates, compatibility paths, or per-template
 barrels.
 
@@ -93,4 +101,6 @@ barrels.
   output;
 - keep unsupported interactions and capability gaps explicit;
 - keep concept screens separate from runtime assets;
+- validate the separate asset bundle before screen delivery and its manifest usages before template
+  scaffolding; report visual review and runtime verification separately;
 - for deterministic artifact shape, read [artifact.md](references/artifact.md).

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;
+- `assets`: portable `bundlePath`, completion `status`, and `entries` describing each icon/image,
+  region usages, provenance, dimensions and visual review; planned assets remain explicit during
+  configuration and must be present for screen/template completion;
 - `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`.

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

@@ -0,0 +1,131 @@
+# Separate runtime assets from screen evidence
+
+Read this reference for `interactive`, `screen`, `screens`, and `template`. Every icon and real image
+region used in a designed screen must have a separately usable asset before screen delivery and
+template promotion. Reuse one file for repeated content across screens and states.
+
+## Asset-first design
+
+During interactive configuration, inventory the intended icon and image regions alongside the
+screen list. Configuration alone may leave files planned. Once the requested screen production
+starts, produce the individual assets as part of that same deliverable. An explicit request for
+assets during `interactive` also authorizes producing them; keep unresolved design choices visible.
+
+For direct `template` requests, perform the same asset preparation before scaffolding, even when
+no concept screens exist. A request that already authorizes creation does not require another
+confirmation merely for these normal asset preparation steps.
+
+- SVG icons: author real vector paths, or reuse matching licensed vector artwork with attribution.
+  Keep a consistent viewBox, geometry and stroke weight. Use `currentColor` for themeable icons.
+  Do not wrap a raster crop or embedded PNG in an SVG. A raster image generator cannot produce
+  true SVG geometry; use vector authoring and validate the XML with an available XML tool.
+- Photos, covers, avatars, logos and illustrations: generate or reuse each distinct image as a
+  separate file with the required crop, resolution and transparency. Use an available image
+  generation/editing tool for new raster content. Do not claim generation when that tool is absent.
+  Preserve suitable user-supplied source assets. For an existing screen image, extract only the
+  image region when its quality is sufficient; otherwise regenerate that region separately.
+- Generate assets before concept screens. Supply those files as image references when creating
+  the screens and inspect that the resulting content matches. For exact fidelity, render a ZORA
+  composition using the files. A concept model's approximation is not proof of exact reuse.
+- Inspect each separate file and the screens visually. If a concept introduces another icon or
+  image, produce that asset and reconcile the inventory before calling the screen deliverable
+  complete. Do not substitute the whole screen image for application content.
+
+Keep one portable design directory until template promotion:
+
+```text
+design-assets.json
+assets/screens/home.png
+assets/images/cover.png
+assets/images/svg/book.svg
+```
+
+Use a task-specific artifact directory for screen-only work. Do not scaffold a template just to
+store its assets. Carry this same bundle into `template`; do not generate a second inconsistent set.
+Changing an asset or screen region invalidates its previous visual review and affected references.
+
+## Asset bundle contract
+
+`design-assets.json` is a handoff inventory, not runtime manifest authority. Source paths are
+relative to its directory; targets are relative to the future template root. Record every runtime
+use as a JSON pointer to the `{ "mediaId": "..." }` reference in the planned/final manifest.
+The normal app model and component schemas still come from the installed owners.
+
+```json
+{
+  "assets": [
+    {
+      "mediaId": "book-icon",
+      "role": "icon",
+      "sourcePath": "assets/images/svg/book.svg",
+      "targetPath": "assets/images/svg/book.svg",
+      "contentType": "image/svg+xml",
+      "usages": ["/navigator/routes/0/icon/source"]
+    },
+    {
+      "mediaId": "book-cover",
+      "role": "image",
+      "sourcePath": "assets/images/cover.png",
+      "targetPath": "assets/images/cover.png",
+      "contentType": "image/png",
+      "usages": ["/screens/home/root/children/0/props/source"]
+    }
+  ],
+  "screens": [{ "sourcePath": "assets/screens/home.png", "targetPath": "assets/screens/home.png" }]
+}
+```
+
+The pointers above are examples; use the actual topology. Empty arrays explicitly declare no
+runtime assets or no screen evidence. Supported portable image files are SVG, PNG, JPEG and WebP.
+Preserve source attribution, generation prompts, region purpose, visual review and dimensions in
+the design artifact's `assets.entries`; do not infer those facts from a filename.
+
+Before handing off screens, run:
+
+```text
+bun .agents/skills/zora-designer/scripts/asset-bundle.ts path/to/design-assets.json
+```
+
+This checks the files, path confinement, duplicates, basic image signatures and standalone SVG
+shape. It does not decode images, parse all XML, assess visual quality or prove runtime rendering.
+Perform those relevant visual/XML checks separately and record their evidence. Missing assets
+block asset completion, not unrelated configuration discussion.
+
+## Manifest and template promotion
+
+Register every bundle asset in `manifest.media.assets` as `kind: image`, with matching `id`,
+`contentType` and bundled `source.path`. SVG icons belong under `assets/images/svg/`; other images
+belong under `assets/images/`. Screen evidence stays under `assets/screens/` and is never media.
+
+Use the existing ZORA `Icon` with `source: { mediaId }` for these SVGs, including navigator icons.
+Use ZORA `Image` with its owner-supported media source for application imagery, or an exact semantic
+component's supported media prop. Do not add an SVG provider or a separate SVG component. Named
+font icons remain valid for existing designs when requested, but do not substitute them for the
+separate SVG assets of this workflow. Inspect current owner metadata and runtime media resolution.
+
+Run the bundle checker with `manifest.json` to check registered assets and actual reference paths.
+Pass the same file as `assetBundlePath` to the scaffolder:
+
+```json
+{
+  "targetDirectory": "/path/to/templates",
+  "category": "books_reading",
+  "slug": "reader",
+  "assetBundlePath": "/path/to/design/design-assets.json",
+  "manifest": {}
+}
+```
+
+Replace the example empty manifest with the complete release-valid owner manifest. The scaffolder
+validates and reads all asset bytes before creating output, copies them to their checked targets,
+and returns every created file. It fails on missing files, dangling media references, unused bundle
+entries, mismatched registrations or invalid paths. Owner release validation remains mandatory.
+
+After scaffolding, inspect the exported template artifact and verify generated runtime usage through
+the consuming app's media resolver. A passing bundle/manifest check alone does not prove that Studio
+or another consumer renders the files. Report missing consumer support explicitly; never call an
+untested runtime path verified.
+
+For generated applications, verify that the installed runtime preserves image media references
+until media resolution (`@ankhorage/runtime` 2.2.6 or newer). The Icon manifest node and normal
+container support for Icon/Image require ZORA 4.2.0 or newer; the owner helper enforces this minimum.

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

@@ -28,7 +28,10 @@ For every screen record:
 4. route relationship and continuity of selected item, filters, progress, drafts, or other state;
 5. exact metadata-backed ZORA elements, supported events/actions, data needs, and capability gaps;
 6. safe areas, keyboard/overlay behavior, scroll ownership, and narrow/wide behavior;
-7. real image content that must become an application asset rather than screenshot UI.
+7. every SVG icon and real image region, its reusable asset ID, and its intended manifest usage.
+
+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.
 
 Create one shared shell specification for a series: viewport, safe areas, gutters, header geometry,
 navigation geometry, surface treatment, type roles, icon family, content density, and state styling.
@@ -72,6 +75,7 @@ Generate one image per distinct screen or state. Every prompt must include:
 - exact screen title, copy that must be legible, hierarchy, components, and primary action;
 - content quantity that fits the viewport at the declared type scale;
 - invariants shared with the other screens;
+- the prepared icon and image assets for every media region, retaining their visual identity;
 - prohibitions against device frames, presentation boards, watermarks, illegible labels, invented
   tabs, and oversized marketing typography on ordinary application screens.
 

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

@@ -42,7 +42,8 @@ Advance through this sequence. Skip only a value already supplied or reliably di
    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.
+   generate images yet. Inventory each icon and image region using
+   [runtime-assets.md](runtime-assets.md), including reused assets and their intended consumers.
 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
@@ -75,9 +76,10 @@ removing the intended flow or inventing a contract.
 - `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.
+  the requested deliverable together with its separate SVG and image asset bundle.
 - `template`: author a complete `AppManifest`, validate it in release mode, generate or extract every
-  required runtime image, and run the Templates scaffolder.
+  required SVG and runtime image, validate the asset bundle against the manifest, and run the
+  Templates scaffolder with `assetBundlePath`.
 
 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

package/dist/tools/skills/assets/zora-designer/scripts/asset-bundle.ts

@@ -0,0 +1,207 @@
+#!/usr/bin/env bun
+
+import { readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { assertAssetPath, assertImageContent, readAssetFile } from './asset-files.ts';
+
+interface AssetEntry {
+  mediaId: string;
+  role: 'icon' | 'image';
+  sourcePath: string;
+  targetPath: string;
+  contentType: string;
+  usages: string[];
+}
+
+export interface PreparedAssetFile {
+  targetPath: string;
+  bytes: Buffer;
+}
+
+/*** Validate a portable design asset bundle before screen handoff or template writes. */
+export async function prepareAssetBundle(
+  bundlePath: string,
+  manifest?: Record<string, unknown>,
+): Promise<PreparedAssetFile[]> {
+  const input: unknown = JSON.parse(await readFile(bundlePath, 'utf8'));
+  assertRecord(input);
+  if (!Array.isArray(input.assets) || !Array.isArray(input.screens)) {
+    throw new Error('Asset bundle requires assets and screens arrays, including when empty.');
+  }
+  const assets = input.assets.map(parseAssetEntry);
+  const ids = assets.map((asset) => asset.mediaId);
+  if (new Set(ids).size !== ids.length) throw new Error('Duplicate asset mediaId.');
+  if (manifest) validateManifestAssets(assets, manifest);
+  const root = dirname(resolve(bundlePath));
+  const files = await Promise.all(
+    assets.map(async (asset) => {
+      const bytes = await readAssetFile(root, asset.sourcePath);
+      assertImageContent(bytes, asset.contentType);
+      return { targetPath: asset.targetPath, bytes };
+    }),
+  );
+  for (const screen of input.screens) {
+    assertRecord(screen);
+    const sourcePath = requireString(screen.sourcePath);
+    const targetPath = requireString(screen.targetPath);
+    assertAssetPath(sourcePath, 'assets/screens/');
+    assertAssetPath(targetPath, 'assets/screens/');
+    files.push({ targetPath, bytes: await readAssetFile(root, sourcePath) });
+  }
+  if (new Set(files.map((file) => file.targetPath.toLowerCase())).size !== files.length) {
+    throw new Error('Duplicate asset targetPath.');
+  }
+  return files;
+}
+
+/*** Parse one generated runtime asset and its manifest JSON-pointer usages. */
+function parseAssetEntry(value: unknown): AssetEntry {
+  assertRecord(value);
+  if (value.role !== 'icon' && value.role !== 'image')
+    throw new Error('Asset role must be icon or image.');
+  const sourcePath = requireString(value.sourcePath);
+  const targetPath = requireString(value.targetPath);
+  const contentType = requireString(value.contentType);
+  const prefix = value.role === 'icon' ? 'assets/images/svg/' : 'assets/images/';
+  assertAssetPath(sourcePath, prefix);
+  assertAssetPath(targetPath, prefix);
+  if (value.role === 'icon' && contentType !== 'image/svg+xml')
+    throw new Error('Icon assets must be SVG.');
+  const extensions: Partial<Record<string, string[]>> = {
+    'image/svg+xml': ['svg'],
+    'image/png': ['png'],
+    'image/jpeg': ['jpg', 'jpeg'],
+    'image/webp': ['webp'],
+  };
+  if (
+    ![sourcePath, targetPath].every((path) =>
+      extensions[contentType]?.includes(path.split('.').at(-1) ?? ''),
+    )
+  ) {
+    throw new Error('Asset extension must match contentType.');
+  }
+  if (!Array.isArray(value.usages) || value.usages.length === 0)
+    throw new Error('Asset usages must identify at least one manifest reference.');
+  const usages = value.usages.map(requireString);
+  if (usages.some((path) => !path.startsWith('/') || path.startsWith('/media/')))
+    throw new Error('Asset usages must point to runtime consumers outside /media/.');
+  return {
+    mediaId: requireString(value.mediaId),
+    role: value.role,
+    sourcePath,
+    targetPath,
+    contentType,
+    usages,
+  };
+}
+
+/*** Match bundled files to registered media and actual runtime references. */
+function validateManifestAssets(assets: AssetEntry[], manifest: Record<string, unknown>): void {
+  const media = manifest.media ?? {};
+  assertRecord(media);
+  const registry = media.assets ?? {};
+  assertRecord(registry);
+  for (const [id, definition] of Object.entries(registry)) {
+    assertRecord(definition);
+    assertRecord(definition.source);
+    if (definition.source.kind !== 'bundled') continue;
+    const asset = assets.find((entry) => entry.mediaId === id);
+    if (
+      !asset ||
+      definition.id !== id ||
+      definition.kind !== 'image' ||
+      definition.source.path !== asset.targetPath ||
+      definition.contentType !== asset.contentType
+    ) {
+      throw new Error(`Bundled media must match an asset entry: ${id}`);
+    }
+  }
+  for (const asset of assets) {
+    const definition = registry[asset.mediaId];
+    assertRecord(definition);
+    assertRecord(definition.source);
+    if (definition.source.kind !== 'bundled')
+      throw new Error(`Asset must register bundled media: ${asset.mediaId}`);
+    for (const usage of asset.usages) {
+      const reference = resolvePointer(manifest, usage);
+      assertRecord(reference);
+      if (reference.mediaId !== asset.mediaId)
+        throw new Error(`Asset usage does not reference ${asset.mediaId}: ${usage}`);
+    }
+  }
+  const { media: _media, ...runtime } = manifest;
+  validateReferences(runtime, registry);
+}
+
+/*** Reject dangling media references anywhere in runtime manifest content. */
+function validateReferences(value: unknown, registry: Record<string, unknown>): void {
+  if (Array.isArray(value)) {
+    value.forEach((item) => validateReferences(item, registry));
+    return;
+  }
+  if (typeof value !== 'object' || value === null) return;
+  if (
+    'mediaId' in value &&
+    typeof value.mediaId === 'string' &&
+    !Object.hasOwn(registry, value.mediaId)
+  )
+    throw new Error(`Unknown runtime mediaId: ${value.mediaId}`);
+  Object.values(value).forEach((item) => validateReferences(item, registry));
+}
+
+/*** Resolve a standard JSON pointer without evaluating paths as code. */
+function resolvePointer(root: unknown, pointer: string): unknown {
+  return pointer
+    .slice(1)
+    .split('/')
+    .reduce<unknown>((value, segment) => {
+      const key = segment.replaceAll('~1', '/').replaceAll('~0', '~');
+      if (Array.isArray(value)) return value[Number(key)];
+      assertRecord(value);
+      return value[key];
+    }, root);
+}
+
+/*** Require a JSON object at the asset input boundary. */
+function assertRecord(value: unknown): asserts value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value))
+    throw new Error('Expected an asset or media object.');
+}
+
+/*** Require a nonempty asset input string. */
+function requireString(value: unknown): string {
+  if (typeof value !== 'string' || value.trim() === '')
+    throw new Error('Expected a nonempty asset string.');
+  return value;
+}
+
+/*** Validate one asset bundle, optionally against a complete manifest. */
+async function main(): Promise<void> {
+  const [bundlePath, manifestPath] = process.argv.slice(2);
+  if (!bundlePath) throw new Error('Usage: asset-bundle.ts <design-assets.json> [manifest.json]');
+  const manifest: unknown = manifestPath
+    ? JSON.parse(await readFile(manifestPath, 'utf8'))
+    : undefined;
+  if (manifest !== undefined) assertRecord(manifest);
+  const files = await prepareAssetBundle(bundlePath, manifest);
+  console.log(
+    JSON.stringify(
+      {
+        status: 'pass',
+        scope: manifest ? 'files-and-references' : 'files',
+        files: files.map((file) => file.targetPath),
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  main().catch((error: unknown) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}

package/dist/tools/skills/assets/zora-designer/scripts/asset-files.ts

@@ -0,0 +1,45 @@
+import { readFile, realpath, stat } from 'node:fs/promises';
+import { resolve, sep } from 'node:path';
+
+/*** Require a portable asset destination without traversal or ambiguous separators. */
+export function assertAssetPath(value: string, prefix: string): void {
+  if (
+    !value.startsWith(prefix) ||
+    value.split('/').some((part) => !part || part === '.' || part === '..') ||
+    /[\\:]/u.test(value) ||
+    [...value].some((character) => character.charCodeAt(0) < 32)
+  ) {
+    throw new Error(`Asset path must be a portable file below ${prefix}: ${value}`);
+  }
+}
+
+/*** Read a nonempty regular source file confined to the asset bundle directory. */
+export async function readAssetFile(root: string, path: string): Promise<Buffer> {
+  assertAssetPath(path, 'assets/');
+  const base = await realpath(root);
+  const source = await realpath(resolve(root, path));
+  if (!source.startsWith(`${base}${sep}`) || !(await stat(source)).isFile()) {
+    throw new Error(`Asset source must be a regular file inside the bundle: ${path}`);
+  }
+  const bytes = await readFile(source);
+  if (bytes.length === 0) throw new Error(`Asset file is empty: ${path}`);
+  return bytes;
+}
+
+/*** Check image signatures and require standalone vector markup for SVG icons. */
+export function assertImageContent(bytes: Buffer, contentType: string): void {
+  const text = bytes.toString('utf8');
+  const signatures: Partial<Record<string, boolean>> = {
+    'image/png': bytes.subarray(0, 8).toString('hex') === '89504e470d0a1a0a',
+    'image/jpeg': bytes.subarray(0, 3).toString('hex') === 'ffd8ff',
+    'image/webp':
+      bytes.subarray(0, 4).toString() === 'RIFF' && bytes.subarray(8, 12).toString() === 'WEBP',
+    'image/svg+xml':
+      /<svg\b[^>]*\bviewBox=["'][^"']+["']/u.test(text) &&
+      /<\/svg>\s*$/u.test(text) &&
+      !/<(?:image|script|foreignObject)\b|<!DOCTYPE|data:image|\b(?:href|onload)\s*=/iu.test(text),
+  };
+  if (signatures[contentType] !== true) {
+    throw new Error(`Asset bytes do not match a supported standalone image: ${contentType}`);
+  }
+}

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

@@ -213,6 +213,7 @@ export function serializeArtifact(input: unknown, audit: unknown) {
     tokens: input.tokens ?? {},
     components: input.components ?? { stateRequirements: [], recipeDecisions: {} },
     screens: input.screens ?? [],
+    assets: input.assets ?? { bundlePath: null, status: 'not-run', entries: [] },
     validation: input.validation ?? {
       scope: documentKind === 'audit' ? 'audit' : 'configuration',
       status: 'not-run',

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

@@ -117,9 +117,9 @@ interface LoadedOwnerModule {
 
 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' },
+  contracts: { packageName: '@ankhorage/contracts', minimumVersion: '10.1.0' },
+  templates: { packageName: '@ankhorage/templates', minimumVersion: '9.3.0' },
+  zora: { packageName: '@ankhorage/zora', minimumVersion: '4.2.0' },
 };
 
 const OWNER_REQUIREMENTS = {

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

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 
 import { access, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
-import { join, relative, resolve, sep } from 'node:path';
+import { dirname, join, relative, resolve, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
 
 import { generateTemplateCatalog } from './generate-template-catalog.ts';
@@ -13,6 +13,7 @@ export async function scaffoldTemplate(input: unknown) {
   assertNonEmptyString(input.targetDirectory, 'targetDirectory');
   assertNonEmptyString(input.category, 'category');
   assertNonEmptyString(input.slug, 'slug');
+  assertNonEmptyString(input.assetBundlePath, 'assetBundlePath');
   const { category, slug, targetDirectory: inputTargetDirectory } = input;
   if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(slug)) {
     throw new Error('slug must be a kebab-case identifier.');
@@ -41,6 +42,10 @@ export async function scaffoldTemplate(input: unknown) {
   const owners = await loadOwnerApis(targetDirectory);
   const composition = owners.templates.validateTemplateManifest(inputManifest, 'release');
   const manifest = owners.templates.assertTemplateManifestReady(composition);
+  const assetFiles = await prepareAssetBundle(
+    resolve(targetDirectory, input.assetBundlePath),
+    manifest,
+  );
 
   const categoryDirectory = resolve(
     targetDirectory,
@@ -59,8 +64,14 @@ export async function scaffoldTemplate(input: unknown) {
 
   const screensDirectory = join(templateDirectory, 'assets', 'screens');
   const imagesDirectory = join(templateDirectory, 'assets', 'images');
+  const svgDirectory = join(imagesDirectory, 'svg');
   await mkdir(screensDirectory, { recursive: true });
-  await mkdir(imagesDirectory, { recursive: true });
+  await mkdir(svgDirectory, { recursive: true });
+  for (const file of assetFiles) {
+    const destination = join(templateDirectory, file.targetPath);
+    await mkdir(dirname(destination), { recursive: true });
+    await writeFile(destination, file.bytes, { flag: 'wx' });
+  }
   await writeFile(
     join(templateDirectory, 'createAppManifest.ts'),
     createManifestSource(manifest),
@@ -72,10 +83,16 @@ export async function scaffoldTemplate(input: unknown) {
   return {
     targetDirectory,
     templateDirectory: relative(targetDirectory, templateDirectory),
-    createdFiles: [relative(targetDirectory, join(templateDirectory, 'createAppManifest.ts'))],
+    createdFiles: [
+      relative(targetDirectory, join(templateDirectory, 'createAppManifest.ts')),
+      ...assetFiles.map((file) =>
+        relative(targetDirectory, join(templateDirectory, file.targetPath)),
+      ),
+    ],
     assetDirectories: [
       relative(targetDirectory, screensDirectory),
       relative(targetDirectory, imagesDirectory),
+      relative(targetDirectory, svgDirectory),
     ],
   };
 }
@@ -146,3 +163,4 @@ if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
     process.exitCode = 1;
   });
 }
+import { prepareAssetBundle } from './asset-bundle.ts';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/devtools",
-  "version": "1.10.15",
+  "version": "1.11.0",
   "description": "Shared development tools and repository standards for Ankhorage",
   "license": "MIT",
   "homepage": "https://github.com/ankhorage/devtools#readme",
@@ -106,10 +106,10 @@
   },
   "dependencies": {
     "@ankhorage/utility": "^0.3.0",
-    "@changesets/cli": "^3.0.1",
+    "@changesets/cli": "^3.0.2",
     "@eslint/compat": "^2.1.1",
     "@eslint/js": "^10.0.1",
-    "eslint": "^10.9.1",
+    "eslint": "^10.10.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-prettier": "^5.5.6",
@@ -126,9 +126,9 @@
   "devDependencies": {
     "@ankhorage/ankh": "^0.8.10",
     "@ankhorage/doctor": "0.10.7",
-    "@types/bun": "^1.4.0",
+    "@types/bun": "^1.4.1",
     "@types/node": "^26.4.1",
     "typescript": "~6.0.3"
   },
-  "packageManager": "bun@1.4.0"
+  "packageManager": "bun@1.4.1"
 }