@iodes/releasekit 0.1.0 → 0.1.2

package/dist/git.js

@@ -1,5 +1,4 @@
 import { spawnSync } from 'node:child_process';
-import { evidenceSchema } from './model.js';
 export function git(cwd, args, input) {
     const result = spawnSync('git', args, {
         cwd, input, encoding: 'utf8', windowsHide: true, maxBuffer: 64 * 1024 * 1024,
@@ -27,7 +26,7 @@ export function isAncestor(root, base, head) {
         return false;
     throw new Error(`Cannot establish Git ancestry: ${result.stderr || result.error?.message}`);
 }
-export function collect(root, from, to) {
+export function resolveRange(root, from, to) {
     if (git(root, ['rev-parse', '--is-shallow-repository']).trim() === 'true') {
         throw new Error('Complete the shallow Git history before preparing a release; no fetch was performed.');
     }
@@ -38,6 +37,11 @@ export function collect(root, from, to) {
     if (fromSha && !isAncestor(root, fromSha, toSha)) {
         throw new Error('The start commit is not an ancestor of the end commit. Choose an explicit range on this release line.');
     }
+    return { fromRef: from, fromSha, toRef: to, toSha };
+}
+export function collect(root, from, to) {
+    const source = resolveRange(root, from, to);
+    const { fromSha, toSha } = source;
     const base = fromSha ?? git(root, ['hash-object', '-t', 'tree', '--stdin'], '').trim();
     const log = git(root, ['log', '--no-show-signature', '--format=%H%x00%s', fromSha ? `${fromSha}..${toSha}` : toSha, '--']);
     const commits = log.trimEnd() ? log.trimEnd().split('\n').map(line => {
@@ -54,14 +58,10 @@ export function collect(root, from, to) {
         else
             files.push({ status, path: first });
     }
-    const patch = git(root, ['diff', '--no-ext-diff', '--no-textconv', '--find-renames', base, toSha, '--']);
-    return {
-        evidence: evidenceSchema.parse({ schemaVersion: 1, source: { fromRef: from, fromSha, toRef: to, toSha }, commits, files }),
-        patch,
-    };
+    return { source, commits, files };
 }
-export function checkPrevious(root, previous, evidence) {
-    const boundary = evidence.source.fromSha;
+export function checkPrevious(root, previous, source) {
+    const boundary = source.fromSha;
     if (!boundary || !isAncestor(root, previous.source.toSha, boundary)) {
         throw new Error('The previous release is not an ancestor of this comparison start. Choose the correct previous release.');
     }

package/dist/images.d.ts

@@ -1,4 +1,4 @@
-import { type Theme, type Visual } from './model.js';
+import { type AssetVariant, type Visual } from './model.js';
 import { Project } from './project.js';
 export declare function inspectImage(bytes: Buffer): Promise<{
     width: number;
@@ -6,13 +6,20 @@ export declare function inspectImage(bytes: Buffer): Promise<{
     extension: string;
     sha256: string;
 }>;
-export interface ImageRequest {
+export type ImageRequest = {
     note: string;
-    theme: Theme;
+    theme: AssetVariant;
     reason: 'missing' | 'stale';
+} & ({
+    action: 'generate';
     promptFile: string;
     compositionReference: string | null;
-}
+} | {
+    action: 'provide';
+    promptFile: null;
+    compositionReference: null;
+    instruction: string;
+});
 export declare function planImages(project: Project, version: string): Promise<{
     version: string;
     configuredThemes: ("dark" | "light")[];
@@ -20,9 +27,11 @@ export declare function planImages(project: Project, version: string): Promise<{
     readyAssets: number;
     pendingAssets: number;
     requests: ImageRequest[];
+    generationRequests: number;
+    providedRequests: number;
     costNote: string;
 }>;
-export declare function importImage(project: Project, version: string, noteId: string, variant: Theme, source: string): Promise<{
+export declare function importImage(project: Project, version: string, noteId: string, variant: AssetVariant, source: string): Promise<{
     file: string;
     sha256: string;
     sceneHash: string;

package/dist/images.js

@@ -1,7 +1,7 @@
 import * as fs from 'node:fs/promises';
 import path from 'node:path';
 import sharp from 'sharp';
-import { themes, theme } from './model.js';
+import { themes, assetVariant, imageSource, activeVariants } from './model.js';
 import { Project, editable } from './project.js';
 import { readVisual, checkReferenceFiles } from './content.js';
 import { digest, identifier, exists, write, writeYaml } from './files.js';
@@ -27,10 +27,11 @@ export async function planImages(project, version) {
     let ready = 0;
     for (const note of release.notes.filter(n => n.image)) {
         const visual = await readVisual(project, version, note.id);
+        const source = imageSource(visual.scene);
         const pair = visual.variants;
         const invalidPair = release.visuals.themes === 'both' && pair.dark && pair.light &&
             (pair.dark.sha256 === pair.light.sha256 || pair.dark.width !== pair.light.width || pair.dark.height !== pair.light.height);
-        for (const variant of themes(release.visuals)) {
+        for (const variant of activeVariants(visual, release.visuals)) {
             const expected = sceneHash(visual.scene, release.visuals, variant);
             const asset = visual.variants[variant];
             const file = asset && await project.releaseFile(version, asset.file);
@@ -41,6 +42,16 @@ export async function planImages(project, version) {
                 continue;
             }
             editable(release);
+            if (source === 'provided') {
+                requests.push({
+                    note: note.id, theme: variant, reason: present ? 'stale' : 'missing', action: 'provide',
+                    promptFile: null, compositionReference: null,
+                    instruction: `Use an existing approved image or ask for a capture, photograph, or content asset for "${visual.scene.subject}". Import the selected file with --theme ${variant}. Do not synthesize a replacement.`,
+                });
+                continue;
+            }
+            if (variant === 'shared')
+                throw new Error('Generated images require a dark or light variant.');
             await checkReferenceFiles(project, visual.scene.references);
             const promptFile = await project.releaseFile(version, `prompts/${note.id}.${variant}.md`);
             await write(promptFile, imagePrompt(visual.scene, release.visuals, variant));
@@ -52,12 +63,14 @@ export async function planImages(project, version) {
                 if (await exists(reference) && digest(await fs.readFile(reference)) === other.sha256)
                     compositionReference = reference;
             }
-            requests.push({ note: note.id, theme: variant, reason: present ? 'stale' : 'missing', promptFile, compositionReference });
+            requests.push({ note: note.id, theme: variant, reason: present ? 'stale' : 'missing', action: 'generate', promptFile, compositionReference });
         }
     }
     return {
         version, configuredThemes: themes(release.visuals), requestedAssets: ready + requests.length,
         readyAssets: ready, pendingAssets: requests.length, requests,
+        generationRequests: requests.filter(request => request.action === 'generate').length,
+        providedRequests: requests.filter(request => request.action === 'provide').length,
         costNote: 'Counts describe required output assets, not provider prices or a guarantee of one tool call per asset. No image service was called.',
     };
 }
@@ -65,12 +78,23 @@ export async function importImage(project, version, noteId, variant, source) {
     const release = await project.release(version);
     editable(release);
     identifier(noteId);
-    theme.parse(variant);
+    assetVariant.parse(variant);
     if (!release.notes.some(n => n.id === noteId && n.image))
         throw new Error(`No image-enabled note named ${noteId}.`);
-    if (!themes(release.visuals).includes(variant))
-        throw new Error(`Theme ${variant} is not enabled for this release. Update the project setting and sync the draft first.`);
     const visual = await readVisual(project, version, noteId);
+    const provided = imageSource(visual.scene) === 'provided';
+    if (variant === 'shared') {
+        if (!provided)
+            throw new Error('Only supplied images can use a shared asset.');
+        if (visual.variants.dark || visual.variants.light)
+            throw new Error('Remove the themed variant entries before switching to one shared supplied image.');
+    }
+    else {
+        if (!themes(release.visuals).includes(variant))
+            throw new Error(`Theme ${variant} is not enabled for this release. Update the project setting and sync the draft first.`);
+        if (visual.variants.shared)
+            throw new Error('Remove the shared variant entry before switching to distinct supplied theme variants.');
+    }
     const bytes = await fs.readFile(path.resolve(project.root, source));
     const inspected = await inspectImage(bytes);
     const file = `assets/${noteId}.${variant}.${inspected.sha256.slice(0, 12)}.${inspected.extension}`;
@@ -90,7 +114,7 @@ export async function importImage(project, version, noteId, variant, source) {
 }
 export async function validateImages(project, version, noteId, visual, errors, warnings) {
     const release = await project.release(version);
-    for (const variant of themes(release.visuals)) {
+    for (const variant of activeVariants(visual, release.visuals)) {
         const expected = sceneHash(visual.scene, release.visuals, variant);
         const asset = visual.variants[variant];
         if (!asset) {
@@ -105,7 +129,7 @@ export async function validateImages(project, version, noteId, visual, errors, w
                 errors.push(`${noteId}: ${variant} asset changed after import; import the selected file again.`);
             }
             const requestedRatio = release.visuals.width / release.visuals.height;
-            if (Math.abs(actual.width / actual.height / requestedRatio - 1) > 0.05) {
+            if (imageSource(visual.scene) === 'generated' && Math.abs(actual.width / actual.height / requestedRatio - 1) > 0.05) {
                 warnings.push(`${noteId}: ${variant} aspect ratio differs from the project target; review its framing.`);
             }
         }

package/dist/model.d.ts

@@ -7,6 +7,12 @@ export declare const theme: z.ZodEnum<{
     light: "light";
 }>;
 export type Theme = z.infer<typeof theme>;
+export declare const assetVariant: z.ZodEnum<{
+    dark: "dark";
+    light: "light";
+    shared: "shared";
+}>;
+export type AssetVariant = z.infer<typeof assetVariant>;
 export declare const paletteSchema: z.ZodObject<{
     canvas: z.ZodString;
     surface: z.ZodString;
@@ -193,6 +199,10 @@ export declare const sceneSchema: z.ZodObject<{
         "symbol-pair": "symbol-pair";
         "ui-detail": "ui-detail";
     }>;
+    source: z.ZodOptional<z.ZodEnum<{
+        generated: "generated";
+        provided: "provided";
+    }>>;
     subject: z.ZodString;
     message: z.ZodString;
     focus: z.ZodString;
@@ -225,6 +235,10 @@ export declare const visualSchema: z.ZodObject<{
             "symbol-pair": "symbol-pair";
             "ui-detail": "ui-detail";
         }>;
+        source: z.ZodOptional<z.ZodEnum<{
+            generated: "generated";
+            provided: "provided";
+        }>>;
         subject: z.ZodString;
         message: z.ZodString;
         focus: z.ZodString;
@@ -251,28 +265,16 @@ export declare const visualSchema: z.ZodObject<{
             width: z.ZodNumber;
             height: z.ZodNumber;
         }, z.core.$strict>>;
+        shared: z.ZodOptional<z.ZodObject<{
+            file: z.ZodString;
+            sha256: z.ZodString;
+            sceneHash: z.ZodString;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strict>>;
     }, z.core.$strict>;
 }, z.core.$strict>;
 export type Visual = z.infer<typeof visualSchema>;
-export declare const evidenceSchema: z.ZodObject<{
-    schemaVersion: z.ZodLiteral<1>;
-    source: z.ZodObject<{
-        fromRef: z.ZodNullable<z.ZodString>;
-        fromSha: z.ZodNullable<z.ZodString>;
-        toRef: z.ZodString;
-        toSha: z.ZodString;
-    }, z.core.$strict>;
-    commits: z.ZodArray<z.ZodObject<{
-        sha: z.ZodString;
-        subject: z.ZodString;
-    }, z.core.$strict>>;
-    files: z.ZodArray<z.ZodObject<{
-        status: z.ZodString;
-        path: z.ZodString;
-        oldPath: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>>;
-}, z.core.$strict>;
-export type Evidence = z.infer<typeof evidenceSchema>;
 export declare const bundleSchema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
     currentVersion: z.ZodString;
@@ -296,6 +298,7 @@ export declare const bundleSchema: z.ZodObject<{
                 fallbackTheme: z.ZodEnum<{
                     dark: "dark";
                     light: "light";
+                    shared: "shared";
                 }>;
                 variants: z.ZodObject<{
                     dark: z.ZodOptional<z.ZodObject<{
@@ -308,6 +311,11 @@ export declare const bundleSchema: z.ZodObject<{
                         width: z.ZodNumber;
                         height: z.ZodNumber;
                     }, z.core.$strict>>;
+                    shared: z.ZodOptional<z.ZodObject<{
+                        src: z.ZodString;
+                        width: z.ZodNumber;
+                        height: z.ZodNumber;
+                    }, z.core.$strict>>;
                 }, z.core.$strict>;
             }, z.core.$strict>>;
         }, z.core.$strict>>;
@@ -315,4 +323,6 @@ export declare const bundleSchema: z.ZodObject<{
 }, z.core.$strict>;
 export type Bundle = z.infer<typeof bundleSchema>;
 export declare function themes(policy: VisualPolicy): Theme[];
+export declare function imageSource(scene: Scene): 'generated' | 'provided';
+export declare function activeVariants(visual: Visual, policy: VisualPolicy): AssetVariant[];
 export declare function defaultConfig(product: string): ProjectConfig;

package/dist/model.js

@@ -3,6 +3,7 @@ export const segment = z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._+-]{0,95}$/);
 export const sha = z.string().regex(/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/);
 export const locale = z.string().regex(/^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/);
 export const theme = z.enum(['dark', 'light']);
+export const assetVariant = z.enum(['dark', 'light', 'shared']);
 const color = z.string().regex(/^#[a-fA-F0-9]{6}$/);
 export const paletteSchema = z.strictObject({
     canvas: color, surface: color, raised: color, primary: color, secondary: color, divider: color,
@@ -47,6 +48,7 @@ export const archetypeSchema = z.enum([
 ]);
 export const sceneSchema = z.strictObject({
     archetype: archetypeSchema,
+    source: z.enum(['generated', 'provided']).optional(),
     subject: z.string().min(1), message: z.string().min(1),
     focus: z.string().min(1), composition: z.string().min(1),
     context: z.string(), elements: z.array(z.string()),
@@ -60,12 +62,7 @@ export const assetSchema = z.strictObject({
 });
 export const visualSchema = z.strictObject({
     schemaVersion: z.literal(1), scene: sceneSchema,
-    variants: z.strictObject({ dark: assetSchema.optional(), light: assetSchema.optional() }),
-});
-export const evidenceSchema = z.strictObject({
-    schemaVersion: z.literal(1), source: sourceSchema,
-    commits: z.array(z.strictObject({ sha, subject: z.string() })),
-    files: z.array(z.strictObject({ status: z.string(), path: z.string(), oldPath: z.string().optional() })),
+    variants: z.strictObject({ dark: assetSchema.optional(), light: assetSchema.optional(), shared: assetSchema.optional() }),
 });
 const exportedImage = z.strictObject({
     src: z.string(), width: z.number().int().positive(), height: z.number().int().positive(),
@@ -77,8 +74,8 @@ export const bundleSchema = z.strictObject({
         notes: z.array(z.strictObject({
             id: segment, category: noteMetaSchema.shape.category, title: z.string(), bodyMarkdown: z.string(),
             image: z.strictObject({
-                alt: z.string(), fallbackTheme: theme,
-                variants: z.strictObject({ dark: exportedImage.optional(), light: exportedImage.optional() }),
+                alt: z.string(), fallbackTheme: assetVariant,
+                variants: z.strictObject({ dark: exportedImage.optional(), light: exportedImage.optional(), shared: exportedImage.optional() }),
             }).nullable(),
         })),
     })),
@@ -86,6 +83,28 @@ export const bundleSchema = z.strictObject({
 export function themes(policy) {
     return policy.themes === 'both' ? ['dark', 'light'] : [policy.themes];
 }
+export function imageSource(scene) {
+    if (scene.archetype === 'object-detail' || scene.archetype === 'editorial-scene') {
+        if (scene.source === 'generated')
+            throw new Error(`${scene.archetype} requires a supplied capture, photograph, or content image. Set source to provided.`);
+        return 'provided';
+    }
+    return scene.source ?? 'generated';
+}
+export function activeVariants(visual, policy) {
+    const provided = imageSource(visual.scene) === 'provided';
+    const { dark, light, shared } = visual.variants;
+    if (shared) {
+        if (!provided)
+            throw new Error('Only supplied images can use a shared asset.');
+        if (dark || light)
+            throw new Error('Choose a shared supplied image or distinct theme variants; do not mix both.');
+        return ['shared'];
+    }
+    if (provided && !dark && !light)
+        return ['shared'];
+    return themes(policy);
+}
 export function defaultConfig(product) {
     return {
         schemaVersion: 1, product, sourceLocale: 'ko-KR', locales: ['ko-KR', 'en-US'],

package/dist/project.d.ts

@@ -1,4 +1,4 @@
-import { type ProjectConfig, type Release, type Evidence } from './model.js';
+import { type ProjectConfig, type Release } from './model.js';
 export declare class Project {
     readonly root: string;
     constructor(root: string);
@@ -10,7 +10,6 @@ export declare class Project {
     release(version: string): Promise<Release>;
     save(release: Release): Promise<void>;
     versions(): Promise<string[]>;
-    evidence(version: string): Promise<Evidence>;
     history(version: string, limit: number): Promise<Release[]>;
 }
 export declare function editable(release: Release): void;

package/dist/project.js

@@ -1,8 +1,8 @@
 import * as fs from 'node:fs/promises';
 import path from 'node:path';
-import { configSchema, releaseSchema, evidenceSchema } from './model.js';
-import { exists, identifier, readYaml, within, writeYaml, write, KIT_DIR } from './files.js';
-import { repoRoot, collect, checkPrevious } from './git.js';
+import { configSchema, releaseSchema } from './model.js';
+import { exists, identifier, readYaml, within, writeYaml, KIT_DIR } from './files.js';
+import { repoRoot, resolveRange, checkPrevious } from './git.js';
 export class Project {
     root;
     constructor(root) { this.root = path.resolve(root); }
@@ -37,9 +37,6 @@ export class Project {
         const entries = await fs.readdir(folder, { withFileTypes: true });
         return entries.filter(e => e.isDirectory()).map(e => e.name).sort();
     }
-    async evidence(version) {
-        return evidenceSchema.parse(JSON.parse(await fs.readFile(await this.releaseFile(version, 'evidence.json'), 'utf8')));
-    }
     async history(version, limit) {
         if (!Number.isInteger(limit) || limit < 1 || limit > 100)
             throw new Error('History limit must be an integer from 1 to 100.');
@@ -77,27 +74,25 @@ export async function prepare(project, version, options) {
     const from = options.fromRoot ? null : options.from ?? previous?.source.toSha;
     if (from === undefined)
         throw new Error('Specify --from, --previous, or --from-root.');
-    const { evidence, patch } = collect(project.root, from, options.to ?? 'HEAD');
+    const source = resolveRange(project.root, from, options.to ?? 'HEAD');
     if (!previous && !options.fromRoot && !options.firstRelease) {
         const existing = await Promise.all((await project.versions()).map(v => project.release(v)));
-        const candidates = existing.filter(r => r.source.toSha === evidence.source.fromSha);
+        const candidates = existing.filter(r => r.source.toSha === source.fromSha);
         if (candidates.length === 1)
             previous = candidates[0];
         else if (existing.length)
             throw new Error('Previous release is ambiguous. Specify --previous, or --first-release for an independent release line.');
     }
     if (previous) {
-        checkPrevious(project.root, previous, evidence);
+        checkPrevious(project.root, previous, source);
         await project.history(previous.version, 1);
     }
     const release = releaseSchema.parse({
         schemaVersion: 1, version, releasedAt: options.date ?? new Date().toISOString().slice(0, 10),
-        previous: previous?.version ?? null, status: 'draft', source: evidence.source,
+        previous: previous?.version ?? null, status: 'draft', source,
         sourceLocale: config.sourceLocale, locales: config.locales, visuals: config.visuals,
         notes: [], emptyReason: null, contentHash: null,
     });
     await project.save(release);
-    await write(await project.releaseFile(version, 'evidence.json'), JSON.stringify(evidence, null, 2) + '\n');
-    await write(await project.releaseFile(version, 'changes.patch'), patch);
     return release;
 }

package/dist/prompts.d.ts

@@ -1,8 +1,8 @@
-import { type Scene, type Theme, type VisualPolicy } from './model.js';
+import { type AssetVariant, type Scene, type Theme, type VisualPolicy } from './model.js';
 export declare const recipes: Record<Scene['archetype'], {
     framing: string;
     treatment: string;
     review: string;
 }>;
-export declare function sceneHash(scene: Scene, policy: VisualPolicy, variant: Theme): string;
+export declare function sceneHash(scene: Scene, policy: VisualPolicy, variant: AssetVariant): string;
 export declare function imagePrompt(scene: Scene, policy: VisualPolicy, variant: Theme): string;

package/dist/prompts.js

@@ -1,14 +1,14 @@
 import { canonical, digest } from './files.js';
-import {} from './model.js';
+import { imageSource } from './model.js';
 export const recipes = {
     'icon-tile': {
-        framing: 'Center one compact symbol or rounded tile. Keep its width around 16–24% of the canvas; allow broad uninterrupted negative space. Use optical centering.',
-        treatment: 'A precise filled glyph or restrained softly modeled icon. One symbol and at most one small status badge. A tile is optional when the naked silhouette is clearer.',
+        framing: 'Center one small flat rounded-square tile, normally 20–24% of the canvas width. Keep the glyph around 50–65% of the tile width. Use optical centering and broad uninterrupted negative space. A naked glyph is appropriate only when the scene explicitly calls for it.',
+        treatment: 'Use a crisp flat 2D filled glyph in one neutral gray value, with negative space for internal details. Keep the canvas and tile uniform and untextured. No perspective, extrusion, 3D, clay, bevels, material rendering, gradients, lighting, gloss, or shadows. Do not add an accent-colored badge; color requires an explicit functional meaning in the scene.',
         review: 'The symbol must communicate the stated capability or status. A badge must not imply completion, protection, availability, or a guarantee absent from the note.',
     },
     'symbol-pair': {
         framing: 'Place two similarly weighted symbols on one horizontal optical axis, centered as a group; a short low-contrast divider can separate them.',
-        treatment: 'Communicate one relationship. Match stroke weight, corner treatment, and perceived size. Use an arrow only when direction itself is part of the feature.',
+        treatment: 'Communicate one relationship with flat 2D filled glyphs. Match visual weight, corner treatment, and perceived size. Use an arrow only when direction itself is part of the feature. Prefer neutral gray; use color only for a stated interaction or semantic status. No rendered materials or sculpted 3D symbols.',
         review: 'Check which two concepts are related and whether the relationship is directional. A connector must not imply transfer, synchronization, or automation unless supported by the note.',
     },
     'ui-detail': {
@@ -18,18 +18,18 @@ export const recipes = {
     },
     'device-view': {
         framing: 'Use one front-facing device or display at roughly 28–48% of the canvas width. A bottom crop is allowed when it enlarges the relevant feature; preserve the entire focus area.',
-        treatment: 'Keep the frame unobtrusive and the screen grounded in supplied product evidence. Use a single device unless cross-device interaction is the feature. Device materials keep their natural appearance in both themes.',
+        treatment: 'Keep any generated frame flat and schematic, with the screen grounded in supplied product evidence. Use a single device unless cross-device interaction is the feature. Choose a supplied capture when actual device appearance matters; do not invent a modeled hardware product.',
         review: 'Check the actual device count, screen content, and relationship between devices. Do not imply an unsupported device, connection, or application theme.',
     },
     'object-detail': {
-        framing: 'Show a close view of the relevant product part; choose a restrained three-quarter or orthographic angle. Preserve feature-defining silhouettes and enough context to recognize the object.',
-        treatment: 'Soft studio lighting and clean matte or authentic product materials. Use quiet depth, contact shadows, and sparse highlights; accent the changed part only. Do not invent an unrelated physical product.',
+        framing: 'Use a supplied image of the relevant product part and retain enough context to recognize it.',
+        treatment: 'Request an authentic product capture, photograph, or approved asset. Preserve the supplied appearance; this category does not create a new physical object or 3D illustration.',
         review: 'Check the feature-defining shape, scale, assembly, contact points, and material against product references. A highlight must not invent a component or change how the object works.',
     },
     'spatial-view': {
-        framing: 'Let a route, spatial diagram, or scene fill the canvas when its topology is necessary. Choose top-down or a single consistent elevated viewpoint; keep the main path or selection readable.',
-        treatment: 'Suppress background detail, use simplified geometry, and preserve conventional route, warning, and selection colors. Display only the layers needed to explain the changed behavior.',
-        review: 'Check positions, connections, direction, scale relationships, and layer meanings against the scene. Routes must remain connected where required, and the graphic must not imply unsupported locations or navigation behavior.',
+        framing: 'Choose the geographic or diagrammatic scale needed to explain the feature, with one consistent viewpoint. A map can reach the canvas edges; reserve quiet space for a supported summary only when the brief calls for it. Do not impose a split layout, coast, road network, or endpoint markers on every spatial scene.',
+        treatment: 'For maps, retain enough fine, low-contrast context to read as a map. Reduce its contrast before deleting its structure: distinguish minor streets, major connections, and land or water through thin linework and flat values. Keep the active route or selection dominant without turning streets into oversized roads or padded checkerboard blocks. Use diagrammatic simplification when relationships alone are the subject. Preserve semantic colors; avoid decorative relief, bevels, textures, and lighting.',
+        review: 'Check positions, connections, direction, scale relationships, and layer meanings against the scene. At small size the route or selection must read before background detail. Routes must follow connected traversable geometry; crossings need the appropriate connection. Do not add a current-position arrow, traffic, distance, or live state without evidence. Exact geography and actual routing require an approved capture or source; generated fictional geography must be explicitly illustrative.',
     },
     'data-view': {
         framing: 'Focus on one panel or device showing one dominant visualization and a few supporting rows. Give the primary metric or interaction clear breathing room.',
@@ -37,17 +37,21 @@ export const recipes = {
         review: 'Check category identity, axes, units, relative values, totals, legends, and any selected filter when present. Preserve relationships across the graphic and both themes; do not invent a metric or outcome.',
     },
     'editorial-scene': {
-        framing: 'Compose one coherent scene around the actual announced experience. Establish a clear foreground subject and quiet supporting background. Keep it legible as a small release card.',
-        treatment: 'Use natural color, rich materials, or playful elements only when they belong to the feature. Reserve this treatment for a content or seasonal experience; it is not the default for routine fixes or settings.',
+        framing: 'Use a supplied capture or approved image of the announced content, with a crop that keeps the subject recognizable.',
+        treatment: 'Request actual content artwork or a screenshot. Preserve its appearance and colors; this category does not invent an editorial still life, illustration, or promotional scene.',
         review: 'Check that the depicted subject and experience match the announced content. Keep essential object relationships coherent and avoid added features, factual promises, or unrelated scenery.',
     },
 };
 export function sceneHash(scene, policy, variant) {
+    if (variant === 'shared' || scene.source === 'provided')
+        return digest(canonical({ scene, variant, source: 'provided' }));
     // Other themes and their palettes must not invalidate this already accepted render.
     const { themes: _themes, dark: _dark, light: _light, ...appearance } = policy;
     return digest(canonical({ scene, appearance, theme: variant, palette: policy[variant] }));
 }
 export function imagePrompt(scene, policy, variant) {
+    if (imageSource(scene) === 'provided')
+        throw new Error('This scene needs a supplied image. Request or import the source instead of generating an illustration.');
     const recipe = recipes[scene.archetype];
     const palette = policy[variant];
     const list = (items) => items.length ? items.map(item => `- ${item}`).join('\n') : '- None';
@@ -57,10 +61,14 @@ export function imagePrompt(scene, policy, variant) {
         `## Composition contract\nArchetype: ${scene.archetype}\nTarget canvas: ${policy.width} × ${policy.height} pixels; landscape ${policy.width}:${policy.height}. Produce a single image, not a dark/light collage.\n${recipe.framing}\nSpecific scene layout: ${scene.composition}\nElements:\n${list(scene.elements)}\n\n` +
         `## Visual treatment\n${recipe.treatment}\nFavor visual precision, quiet hierarchy, and one instantly understandable feature. Small-screen clarity takes priority over decorative detail. Treat the specified element inventory as complete. Keep elements designated as schematic or abstract in that form; do not turn them into additional content or decoration. Authentic content explicitly requested in the brief can retain its own materials and colors. Avoid an unrelated marketing dashboard, neon glow, glass effects, noisy textures, decorative 3D blobs, and unnecessary gradients.\n\n` +
         `## ${variant === 'dark' ? 'Dark' : 'Light'} theme roles\n` +
-        `Canvas ${palette.canvas}; base surface ${palette.surface}; raised surface ${palette.raised}; main neutral symbol ${palette.primary}; secondary detail ${palette.secondary}; divider ${palette.divider}; interaction accent ${policy.accent}.\n` +
-        (variant === 'dark'
-            ? 'Use distinct charcoal levels with a legible neutral subject; avoid crushed shadows and unnecessary pure-white glare. Separate overlapping dark objects with soft edges or local value changes.\n'
-            : 'Use a near-white canvas, subtle surface separation, restrained contact shadows, and medium-dark neutral symbols. Avoid both flat white-on-white disappearance and thick dark outlines.\n') +
+        `Canvas ${palette.canvas}; base surface ${palette.surface}; raised surface ${palette.raised}; main neutral symbol ${palette.primary}; secondary detail ${palette.secondary}; divider ${palette.divider}; interaction accent ${policy.accent}. Use the accent only when the scene assigns it a functional meaning.\n` +
+        (scene.archetype === 'icon-tile' || scene.archetype === 'symbol-pair'
+            ? `Use uniform flat color areas and crisp negative space. If a tile is present, use ${variant === 'dark' ? palette.surface : palette.raised} for its flat fill. Separate the neutral glyph and its background by value alone. Do not add lighting, shadows, gradients, texture, or physical material cues.\n`
+            : scene.archetype === 'spatial-view'
+                ? 'Use flat value separation and crisp linework. Keep background layers subordinate to the focal route or selection in this theme. Do not add contact shadows, studio lighting, bevels, or material shading. A local fade into quiet space is allowed only when specified by the scene.\n'
+                : variant === 'dark'
+                    ? 'Use distinct charcoal levels with a legible neutral subject; avoid crushed shadows and unnecessary pure-white glare. Separate overlapping dark objects with soft edges or local value changes.\n'
+                    : 'Use a near-white canvas, subtle surface separation, restrained contact shadows, and medium-dark neutral symbols. Avoid both flat white-on-white disappearance and thick dark outlines.\n') +
         `Treat these colors as presentation roles, not a global recoloring filter. Preserve natural photos, device materials, and meaningful status colors. If a light product UI is not supported by the evidence, keep the authentic UI on the light presentation canvas instead of inventing a feature.\n\n` +
         `## Pair invariants\nThe other theme must use the same object count, positions, scale, crop, camera, UI topology, selected state, chart values, allowed labels, and feature meaning. Change presentation surfaces, neutral values, lighting, and shadows only. Preserve semantic accent hues. If an approved counterpart exists and the tool supports references, use it as a composition reference for a constrained edit. Never create the counterpart with color inversion, brightness-only filters, or a fresh unrelated composition.\nSpecific invariants:\n${list(scene.preserve)}\n\n` +
         `## Text and references\n` +

package/dist/schema-export.js

@@ -1,10 +1,17 @@
 import * as fs from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
-import { configSchema, releaseSchema, visualSchema, noteTextSchema, evidenceSchema, bundleSchema } from './model.js';
+import { configSchema, releaseSchema, visualSchema, noteTextSchema, bundleSchema } from './model.js';
 const directory = fileURLToPath(new URL('../schemas/', import.meta.url));
 await fs.mkdir(directory, { recursive: true });
-for (const [name, schema] of Object.entries({ config: configSchema, release: releaseSchema, visual: visualSchema, note: noteTextSchema, evidence: evidenceSchema, bundle: bundleSchema })) {
+const schemas = { config: configSchema, release: releaseSchema, visual: visualSchema, note: noteTextSchema, bundle: bundleSchema };
+for (const [name, schema] of Object.entries(schemas)) {
     const json = { ...z.toJSONSchema(schema), $id: `urn:releasekit:${name}:1` };
     await fs.writeFile(`${directory}/${name}.schema.json`, JSON.stringify(json, null, 2) + '\n');
 }
+// Keep the generated directory aligned with the schemas the package exports.
+const outputs = new Set(Object.keys(schemas).map(name => `${name}.schema.json`));
+for (const file of await fs.readdir(directory)) {
+    if (file.endsWith('.schema.json') && !outputs.has(file))
+        await fs.unlink(`${directory}/${file}`);
+}

package/dist/validate.js

@@ -1,13 +1,12 @@
-import * as fs from 'node:fs/promises';
-import {} from './model.js';
+import { imageSource } from './model.js';
 import { Project, editable } from './project.js';
 import { canonical, digest, readNote, noteHash, identifier } from './files.js';
 import { readVisual, checkReferenceFiles } from './content.js';
 import { validateImages } from './images.js';
-import { checkPrevious } from './git.js';
+import { checkPrevious, collect } from './git.js';
 export async function contentHash(project, release) {
     const { status: _status, contentHash: _hash, ...metadata } = release;
-    const parts = [metadata, await project.evidence(release.version), digest(await fs.readFile(await project.releaseFile(release.version, 'changes.patch')))];
+    const parts = [metadata];
     for (const note of release.notes) {
         for (const language of release.locales)
             parts.push(await readNote(await project.releaseFile(release.version, `notes/${note.id}/${language}.md`)));
@@ -21,9 +20,8 @@ export async function validate(project, version) {
     let hash = null;
     try {
         const release = await project.release(version);
-        const evidence = await project.evidence(version);
-        if (canonical(evidence.source) !== canonical(release.source))
-            errors.push('Evidence and release Git boundaries disagree.');
+        // Drafts inspect the pinned Git range. Ready releases rely on their finalized fingerprint.
+        const evidence = release.status === 'draft' ? collect(project.root, release.source.fromSha, release.source.toSha) : null;
         if (!release.locales.includes(release.sourceLocale) || new Set(release.locales).size !== release.locales.length)
             errors.push('Release locales must be unique and include the source locale.');
         if (new Set(release.notes.map(n => n.id)).size !== release.notes.length)
@@ -32,13 +30,13 @@ export async function validate(project, version) {
             errors.push('No notes yet. Write the notes or explain the absence of user-visible changes in emptyReason.');
         if (release.notes.length && release.emptyReason !== null)
             errors.push('emptyReason must be null when notes are present.');
-        const commits = new Set(evidence.commits.map(c => c.sha));
-        const changedPaths = new Set(evidence.files.flatMap(f => [f.path, ...(f.oldPath ? [f.oldPath] : [])]));
+        const commits = new Set(evidence?.commits.map(c => c.sha));
+        const changedPaths = new Set(evidence?.files.flatMap(f => [f.path, ...(f.oldPath ? [f.oldPath] : [])]));
         for (const note of release.notes) {
             identifier(note.id);
             if (!note.commits.length && !note.paths.length)
                 errors.push(`${note.id}: attach at least one changed path or commit as evidence.`);
-            if (note.commits.some(c => !commits.has(c)) || note.paths.some(p => !changedPaths.has(p)))
+            if (evidence && (note.commits.some(c => !commits.has(c)) || note.paths.some(p => !changedPaths.has(p))))
                 errors.push(`${note.id}: evidence points outside the prepared Git range.`);
             try {
                 const source = await readNote(await project.releaseFile(version, `notes/${note.id}/${release.sourceLocale}.md`));
@@ -60,7 +58,7 @@ export async function validate(project, version) {
             if (note.image) {
                 try {
                     const visual = await readVisual(project, version, note.id);
-                    if (release.status === 'draft')
+                    if (release.status === 'draft' && imageSource(visual.scene) === 'generated')
                         await checkReferenceFiles(project, visual.scene.references);
                     await validateImages(project, version, note.id, visual, errors, warnings);
                 }
@@ -77,7 +75,7 @@ export async function validate(project, version) {
         }
         if (release.status === 'draft' && release.previous) {
             try {
-                checkPrevious(project.root, await project.release(release.previous), evidence);
+                checkPrevious(project.root, await project.release(release.previous), release.source);
             }
             catch (error) {
                 errors.push(error instanceof Error ? error.message : String(error));