@neatico/visual-core 0.0.0-stage → 0.14.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 PowerDuckie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,245 @@
-# Temporary Holding Version
+<div align="center">
+  <a href="https://www.neatico.com/?utm_source=npm&utm_medium=readme&utm_campaign=visual-core">
+    <img src="https://www.neatico.com/brand/neatico-logo.svg" width="240" alt="Neatico" />
+  </a>
+  <h1>@neatico/visual-core</h1>
+  <p>Framework-independent geometry, measured text wrapping, and extensible scene registries for visual editors.</p>
+  <p>
+    <a href="https://www.npmjs.com/package/@neatico/visual-core"><img src="https://img.shields.io/npm/v/@neatico/visual-core.svg?style=flat-square&label=npm" alt="npm version" /></a>
+    <a href="https://github.com/neatico/visual-core"><img src="https://img.shields.io/badge/source-github-111827?style=flat-square" alt="source" /></a>
+    <img src="https://img.shields.io/badge/license-MIT-10b981?style=flat-square" alt="license: MIT" />
+    <img src="https://img.shields.io/badge/node-%3E%3D20-6366f1?style=flat-square" alt="node >=20" />
+  </p>
+</div>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+---
+
+`@neatico/visual-core` is the layout engine that powers Neatico's AI design canvas. It is pure, data-first, and free of React, the DOM, a database, and any AI provider — so you can run it on a server, in a worker, or inside your own editor.
+
+It provides the pieces a serious visual editor needs:
+
+- **Affine geometry** — group/child transforms that survive ungrouping.
+- **Measured text wrapping** — UAX #14 line breaks driven by *your* font metrics.
+- **Source-backed content model** — validate untrusted AI output without trusting generated code or asset URLs.
+- **Data-only compositions & blueprints** — portable, versioned layout descriptions with no executable markup.
+- **Layout eligibility** — 97 presentation and 97 social layouts with semantic contracts.
+- **Themes, fonts, and pagination** — deterministic token sets and lossless content splitting.
+
+## Installation
+
+```sh
+npm install @neatico/visual-core
+```
+
+Ships as native ES modules, CommonJS, and TypeScript declarations. Requires Node.js 20+ (the only runtime dependency is the MIT-licensed [`linebreak`](https://github.com/foliojs/linebreak) for Unicode line opportunities).
+
+## Contents
+
+- [Preserve transforms when ungrouping](#preserve-transforms-when-ungrouping)
+- [Wrap text with your font measurements](#wrap-text-with-your-font-measurements)
+- [Add custom scenes](#add-custom-scenes)
+- [Validate AI-authored content](#validate-ai-authored-content)
+- [Validate compositions and blueprints](#validate-compositions-and-blueprints)
+- [Select layout candidates](#select-layout-candidates)
+- [Paginate without losing content](#paginate-without-losing-content)
+- [Themes, fonts, and fingerprints](#themes-fonts-and-fingerprints)
+- [API surface](#api-surface)
+
+## Preserve transforms when ungrouping
+
+```ts
+import { flattenGroupLayout } from "@neatico/visual-core";
+
+const group = { x: 100, y: 50, width: 400, height: 300, rotation: 30 };
+const child = { x: 20, y: 30, width: 120, height: 60, rotation: 15 };
+const ungrouped = flattenGroupLayout(group, child);
+```
+
+Coordinates are in logical canvas units; rotations and skew are in degrees with the element center as the origin. `flattenGroupLayout` preserves additional child properties and returns a new object. It supports translation, rotation, scaling, skew, and horizontal/vertical flips. Nonfinite values, negative dimensions, and degenerate transforms fail explicitly.
+
+Also exported: `layoutMatrix`, `multiplyMatrix`, `layoutBounds`, plus the `Layout` and `Matrix` types. Matrices use the six-value CSS affine format `[a, b, c, d, e, f]`.
+
+## Wrap text with your font measurements
+
+```ts
+import { wrapCopy } from "@neatico/visual-core";
+
+const ctx = document.createElement("canvas").getContext("2d")!;
+await document.fonts.load("400 24px Inter");
+
+const lines = wrapCopy(
+  "One idea. Every format.",
+  240,
+  24,
+  false,
+  (text, size, bold) => {
+    ctx.font = `${bold ? 700 : 400} ${size}px Inter`;
+    return ctx.measureText(text).width;
+  },
+);
+```
+
+You supply measurements for the actual font the renderer uses. Explicit line breaks are preserved; opportunities follow UAX #14 (Unicode 13), oversized tokens use grapheme boundaries via `Intl.Segmenter`, and a grapheme wider than the line fails rather than silently clipping. Tiny trailing lines are balanced unless you pass `{ balance: false }`. Titles can use `{ keepWords: true, preferClauseBreaks: true }`. Returned lines are plain text — escape them before inserting into HTML.
+
+## Add custom scenes
+
+```ts
+import { createSceneRegistry } from "@neatico/visual-core";
+
+type Brief = { headline: string };
+type Scene = { text: string; accent: string };
+
+const scenes = createSceneRegistry<Brief, Scene>();
+const unregister = scenes.register("product-launch", (brief) => ({
+  text: brief.headline,
+  accent: "#6950e8",
+}));
+
+const scene = scenes.render("product-launch", { headline: "Meet your next idea." });
+unregister();
+```
+
+Each registry is isolated; duplicate names and unknown scenes throw. Renderers own their input validation and output schema, so async renderers and custom canvas/SVG representations are supported. No global registry is created.
+
+## Validate AI-authored content
+
+```ts
+import { parseSource, validateContentPlan } from "@neatico/visual-core";
+
+const source = parseSource(rawInputText);
+const plan = validateContentPlan(aiJson, source, "presentation");
+```
+
+`validateContentPlan` is a hard boundary for untrusted model output. It strips unknown properties, never trusts generated code or asset URLs, and verifies content against the source ranges. File-name placeholders are treated as references, not fabricated assets. Use `validateEditableContentPage` for editor-authored pages (pass `{ allowIncomplete: true }` while the user is still editing).
+
+## Validate compositions and blueprints
+
+```ts
+import {
+  validateComposition,
+  compositionFields,
+  createBlueprintRegistry,
+  blueprintLabel,
+} from "@neatico/visual-core";
+
+const fields = compositionFields(aiContent);
+const composition = validateComposition(aiComposition, fields);
+
+const catalog = createBlueprintRegistry();
+const unregister = catalog.register({
+  version: 1,
+  id: "editorial-introduction",
+  labels: { en: "Editorial introduction", zh: "编辑式导言" },
+  fields: ["title", "body"],
+  ratios: [1, 16 / 9],
+  intents: ["cover"],
+  composition: {
+    version: 1,
+    root: {
+      type: "column",
+      children: [
+        { type: "text", bind: "title", role: "hero" },
+        { type: "text", bind: "body", role: "body" },
+      ],
+    },
+  },
+});
+
+const choices = catalog.find(["title", "body"], 16 / 9, "cover");
+const name = blueprintLabel(choices[0], "zh-CN");
+unregister();
+```
+
+Compositions and blueprints are **data-only** (`version: 1`). There are no coordinates, CSS, HTML, or URLs in the tree; every text node binds exactly one existing, nonempty content field. Blueprints can declare semantic `intents`; a cover-only template will never be picked for a closing slide. Field matching is exact, so a template cannot silently drop extra user content. Locale lookup tries the exact locale, then the language, then English.
+
+Structural validation is not visual approval. Before registering AI-authored templates in production, render representative samples at every supported ratio with real font metrics and check bounds, collisions, readability, and content preservation. The host owns persistence, permissions, review, and migration.
+
+## Select layout candidates
+
+```ts
+import { eligibleLayouts, layoutCandidates } from "@neatico/visual-core";
+
+const eligible = eligibleLayouts("presentation", contentPage, 16 / 9);
+const shortlist = layoutCandidates("presentation", "cover", contentPage, 16 / 9, 5);
+```
+
+`LAYOUT_CONTRACTS` covers all 97 presentation and 97 social layout IDs with semantic intent, item capacity, required fields, and ratio bounds. Eligibility is a first filter only — it never replaces measured fit. The host must still measure emitted geometry, confirm every source field is visible, and reject or paginate unreadable output.
+
+## Paginate without losing content
+
+```ts
+import { splitCopy, splitContent } from "@neatico/visual-core";
+
+const copySplit = splitCopy(longParagraph); // [head, tail] | undefined
+const pageSplit = splitContent(overflowingPage); // [pageA, pageB] | undefined
+```
+
+Splits happen only at explicit word/sentence boundaries. Identifiers, decimal values, and unbroken URLs are never cut to force them onto a smaller canvas. The host keeps the title and context on each emitted page and remeasures.
+
+## Themes, fonts, and fingerprints
+
+```ts
+import {
+  designTheme,
+  designCandidates,
+  structureFingerprint,
+  recommendedFonts,
+} from "@neatico/visual-core";
+
+const theme = designTheme("ink");
+const recipes = designCandidates(page, { kind: "social", ratio: 1, limit: 5 });
+
+const fp = structureFingerprint(placedItems, canvasWidth, canvasHeight);
+const fonts = recommendedFonts("ja-JP", japaneseHeadline);
+```
+
+- `DESIGN_THEMES` / `designTheme` expose complete, deterministic palette, typography, and geometry tokens.
+- `designCandidates` ranks authored catalog recipes against a page, excluding already-used families.
+- `structureFingerprint` ignores color, copy, and generated IDs — a preview that only recolors has the same fingerprint.
+- `recommendedFonts`, `contentScript`, and `languageFont` resolve the curated Google Fonts catalog to scripts and supported weights.
+
+## API surface
+
+| Module | Key exports |
+|---|---|
+| Geometry | `layoutMatrix`, `multiplyMatrix`, `flattenGroupLayout`, `layoutBounds`, `Layout`, `Matrix` |
+| Text | `wrapCopy`, `Measure`, `WrapOptions` |
+| Scenes | `createSceneRegistry`, `SceneRenderer` |
+| Content | `parseSource`, `validateContentPlan`, `validateEditableContentPage`, `contentBlockText`, `ContentPlan`, `ContentPage`, `ContentBlock` |
+| Composition | `validateComposition`, `compositionFields`, `COMPOSITION_PROMPT`, `Composition` |
+| Blueprints | `validateBlueprint`, `createBlueprintRegistry`, `blueprintLabel` |
+| Design blueprints | `validateDesignBlueprint`, `blueprintFitsContent`, `DesignBlueprint` |
+| Layout contracts | `LAYOUT_CONTRACTS`, `eligibleLayouts`, `layoutCandidates` |
+| Layout catalogs | `PRESENTATION_LAYOUT_IDS`, `SOCIAL_LAYOUT_CATALOG`, `COMPOSITION_SCENES` |
+| Pagination | `splitCopy`, `splitContent` |
+| Design system | `DESIGN_THEMES`, `designTheme`, `DESIGN_RECIPES`, `designCandidates`, `structureFingerprint` |
+| Editorial | `readingUnits`, `needsEditorialPagination`, `ensurePresentationBookends` |
+| Fonts | `GOOGLE_FONT_CATALOG`, `contentScript`, `recommendedFonts`, `languageFont` |
+
+## Design philosophy
+
+Neatico generates genuinely different designs for different stories, not the same template recolored. That principle is encoded here: eligibility is structural but measured fit stays mandatory, compositions are data-only, and registries are isolated so an application can bring its own renderers and approve its own templates. Every validator fails explicitly rather than guessing.
+
+## Development
+
+```sh
+npm install
+npm test          # builds ESM/CJS, then runs node:test
+npm pack --dry-run
+```
+
+Tests cover transform equivalence, invalid geometry, text wrapping, content validation, registry isolation, and pagination. `npm pack` runs the build and tests before assembling the package; only compiled output, this README, and the license are published.
+
+## Meet Neatico
+
+This package is the open-source layout core of **[Neatico](https://www.neatico.com/?utm_source=npm&utm_medium=readme&utm_campaign=visual-core)** — the AI workspace that turns a single idea into pixel-perfect, fully editable visuals. Describe it once and Neatico designs social posts, presentations, and marketing graphics with real layouts, measured typography, your brand kit, AI imagery and background removal, and one-click PPTX/PNG export.
+
+The `@neatico/*` packages are the framework-independent pieces extracted from that product so you can build your own editor, generate-and-go pipeline, or scene extension. Want the finished experience instead of the primitives? **[Start creating free on neatico.com →](https://www.neatico.com/?utm_source=npm&utm_medium=readme&utm_campaign=visual-core)**
+
+## Contributing
+
+Open an issue or pull request at [neatico/visual-core](https://github.com/neatico/visual-core) with a minimal reproduction and a regression test. Keep APIs independent of application state and use American English in documentation and code comments.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/dist/blueprints.d.ts

@@ -0,0 +1,20 @@
+import { type Composition } from './composition.js';
+/** Portable AI-authored template. Applications own approval and visual checks. */
+export interface Blueprint {
+    version: 1;
+    id: string;
+    labels: Record<string, string>;
+    fields: string[];
+    ratios: number[];
+    /** Optional semantic layout/scene IDs. Omit only for intentionally generic layouts. */
+    intents?: string[];
+    composition: Composition;
+}
+export declare function validateBlueprint(raw: unknown): Blueprint;
+/** Register only after the application has approved representative rendered samples. */
+export declare function createBlueprintRegistry(): {
+    register(raw: unknown): () => void;
+    list(): Blueprint[];
+    find(fields: string[], ratio: number, intent?: string): Blueprint[];
+};
+export declare function blueprintLabel(blueprint: Blueprint, locale: string): string;

package/dist/blueprints.js

@@ -0,0 +1,43 @@
+import { validateComposition } from './composition.js';
+export function validateBlueprint(raw) {
+    const value = raw;
+    if (!value || value.version !== 1 || typeof value.id !== 'string' || !/^[a-z][a-z0-9-]{0,79}$/.test(value.id))
+        throw new Error('Invalid blueprint identity');
+    if (!value.labels || typeof value.labels !== 'object' || Array.isArray(value.labels) || !value.labels.en)
+        throw new Error('Missing blueprint labels');
+    const labels = {};
+    for (const [locale, label] of Object.entries(value.labels)) {
+        if (!/^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/.test(locale) || typeof label !== 'string' || !label.trim() || label.length > 120)
+            throw new Error('Invalid blueprint label');
+        labels[locale] = label.trim();
+    }
+    if (!Array.isArray(value.fields) || !value.fields.length || value.fields.length > 40 || new Set(value.fields).size !== value.fields.length || value.fields.some(field => typeof field !== 'string' || !/^(title|headline|body|eyebrow|cta|value|attribution|items\.\d{1,2}\.(title|description))$/.test(field)))
+        throw new Error('Invalid blueprint fields');
+    if (!Array.isArray(value.ratios) || !value.ratios.length || value.ratios.length > 16 || value.ratios.some(r => !Number.isFinite(r) || r < .25 || r > 4))
+        throw new Error('Invalid blueprint ratios');
+    if (value.intents !== undefined && (!Array.isArray(value.intents) || !value.intents.length || value.intents.length > 32 || value.intents.some(intent => typeof intent !== 'string' || !/^[a-z][a-z0-9-]{0,79}$/.test(intent))))
+        throw new Error('Invalid blueprint intents');
+    return { version: 1, id: value.id, labels, ...(value.intents ? { intents: [...new Set(value.intents)] } : {}), fields: [...value.fields], ratios: [...new Set(value.ratios)], composition: validateComposition(value.composition, Object.fromEntries(value.fields.map(field => [field, 'content']))) };
+}
+/** Register only after the application has approved representative rendered samples. */
+export function createBlueprintRegistry() {
+    const entries = new Map();
+    const copy = (entry) => validateBlueprint(entry);
+    return {
+        register(raw) {
+            const entry = validateBlueprint(raw);
+            if (entries.has(entry.id))
+                throw new Error('Blueprint already registered');
+            entries.set(entry.id, entry);
+            return () => { if (entries.get(entry.id) === entry)
+                entries.delete(entry.id); };
+        },
+        list() { return [...entries.values()].map(copy); },
+        find(fields, ratio, intent) {
+            return [...entries.values()].filter(entry => (!entry.intents || (intent !== undefined && entry.intents.includes(intent))) && entry.fields.length === fields.length && entry.fields.every(field => fields.includes(field)) && entry.ratios.some(r => Math.abs(r - ratio) < .001)).map(copy);
+        },
+    };
+}
+export function blueprintLabel(blueprint, locale) {
+    return blueprint.labels[locale] || blueprint.labels[locale.split('-')[0]] || blueprint.labels.en;
+}

package/dist/cjs/blueprints.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateBlueprint = validateBlueprint;
+exports.createBlueprintRegistry = createBlueprintRegistry;
+exports.blueprintLabel = blueprintLabel;
+const composition_js_1 = require("./composition.js");
+function validateBlueprint(raw) {
+    const value = raw;
+    if (!value || value.version !== 1 || typeof value.id !== 'string' || !/^[a-z][a-z0-9-]{0,79}$/.test(value.id))
+        throw new Error('Invalid blueprint identity');
+    if (!value.labels || typeof value.labels !== 'object' || Array.isArray(value.labels) || !value.labels.en)
+        throw new Error('Missing blueprint labels');
+    const labels = {};
+    for (const [locale, label] of Object.entries(value.labels)) {
+        if (!/^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/.test(locale) || typeof label !== 'string' || !label.trim() || label.length > 120)
+            throw new Error('Invalid blueprint label');
+        labels[locale] = label.trim();
+    }
+    if (!Array.isArray(value.fields) || !value.fields.length || value.fields.length > 40 || new Set(value.fields).size !== value.fields.length || value.fields.some(field => typeof field !== 'string' || !/^(title|headline|body|eyebrow|cta|value|attribution|items\.\d{1,2}\.(title|description))$/.test(field)))
+        throw new Error('Invalid blueprint fields');
+    if (!Array.isArray(value.ratios) || !value.ratios.length || value.ratios.length > 16 || value.ratios.some(r => !Number.isFinite(r) || r < .25 || r > 4))
+        throw new Error('Invalid blueprint ratios');
+    if (value.intents !== undefined && (!Array.isArray(value.intents) || !value.intents.length || value.intents.length > 32 || value.intents.some(intent => typeof intent !== 'string' || !/^[a-z][a-z0-9-]{0,79}$/.test(intent))))
+        throw new Error('Invalid blueprint intents');
+    return { version: 1, id: value.id, labels, ...(value.intents ? { intents: [...new Set(value.intents)] } : {}), fields: [...value.fields], ratios: [...new Set(value.ratios)], composition: (0, composition_js_1.validateComposition)(value.composition, Object.fromEntries(value.fields.map(field => [field, 'content']))) };
+}
+/** Register only after the application has approved representative rendered samples. */
+function createBlueprintRegistry() {
+    const entries = new Map();
+    const copy = (entry) => validateBlueprint(entry);
+    return {
+        register(raw) {
+            const entry = validateBlueprint(raw);
+            if (entries.has(entry.id))
+                throw new Error('Blueprint already registered');
+            entries.set(entry.id, entry);
+            return () => { if (entries.get(entry.id) === entry)
+                entries.delete(entry.id); };
+        },
+        list() { return [...entries.values()].map(copy); },
+        find(fields, ratio, intent) {
+            return [...entries.values()].filter(entry => (!entry.intents || (intent !== undefined && entry.intents.includes(intent))) && entry.fields.length === fields.length && entry.fields.every(field => fields.includes(field)) && entry.ratios.some(r => Math.abs(r - ratio) < .001)).map(copy);
+        },
+    };
+}
+function blueprintLabel(blueprint, locale) {
+    return blueprint.labels[locale] || blueprint.labels[locale.split('-')[0]] || blueprint.labels.en;
+}

package/dist/cjs/composition.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMPOSITION_PROMPT = void 0;
+exports.compositionFields = compositionFields;
+exports.validateComposition = validateComposition;
+exports.COMPOSITION_PROMPT = `Also return composition:{version:1,root:node}. Design a hierarchy from the content, not a fixed template. A node is {type,weight?,tone?,role?,bind?,icon?,children?}. row and column contain 2-4 children; nest up to 5 levels, at most 40 nodes. Weight is relative space 0.5-4. Tone plain/card/contrast applies to groups. Text binds exactly one existing nonempty content field (title or headline, body, eyebrow, cta, value, attribution, items.0.title, items.0.description, etc); never bind notes. Include EVERY nonempty content field exactly once. Text role hero/heading/body/caption controls typography. Image is an optional original conceptual illustration, not invented evidence or a photo. Icon optionally uses idea/check/chart/people/shield/arrow. Divider separates related content. No coordinates, CSS, HTML, URLs or text in the tree. Use one strong hero, purposeful contrast, asymmetric columns, grouped evidence, and breathing room. Rows reflow for narrow formats. Different stories should have different trees, not just different colors.`;
+function compositionFields(value) {
+    const fields = {};
+    for (const key of ['title', 'headline', 'body', 'eyebrow', 'cta', 'value', 'attribution'])
+        if (typeof value[key] === 'string' && value[key].trim())
+            fields[key] = value[key];
+    if (Array.isArray(value.items))
+        value.items.forEach((item, i) => { if (!item || typeof item !== 'object')
+            return; for (const key of ['title', 'description']) {
+            if (!Object.prototype.hasOwnProperty.call(item, key))
+                continue;
+            const v = item[key];
+            if (typeof v === 'string' && v.trim())
+                fields[`items.${i}.${key}`] = v;
+        } });
+    return fields;
+}
+function validateComposition(raw, fields) {
+    const value = raw;
+    let count = 0, images = 0;
+    const seen = new Set();
+    if (!value || value.version !== 1)
+        throw new Error('Unsupported composition');
+    function visit(n, depth) {
+        if (!n || typeof n !== 'object' || ++count > 40 || depth > 5 || !['row', 'column', 'text', 'image', 'divider', 'icon'].includes(n.type))
+            throw new Error('Invalid composition node');
+        if (n.weight !== undefined && (!Number.isFinite(n.weight) || n.weight < .5 || n.weight > 4))
+            throw new Error('Invalid composition weight');
+        if (n.tone !== undefined && !['plain', 'card', 'contrast'].includes(n.tone))
+            throw new Error('Invalid composition tone');
+        const out = { type: n.type, weight: n.weight, tone: n.tone };
+        if (n.type === 'row' || n.type === 'column') {
+            if (!Array.isArray(n.children) || n.children.length < 2 || n.children.length > 4)
+                throw new Error('Invalid composition group');
+            out.children = n.children.map(c => visit(c, depth + 1));
+        }
+        else {
+            if (n.children !== undefined)
+                throw new Error('Leaf cannot have children');
+            if (n.type === 'text') {
+                if (!n.bind || !Object.prototype.hasOwnProperty.call(fields, n.bind) || seen.has(n.bind))
+                    throw new Error('Invalid or duplicated binding');
+                if (n.role !== undefined && !['hero', 'heading', 'body', 'caption'].includes(n.role))
+                    throw new Error('Invalid text role');
+                seen.add(n.bind);
+                out.bind = n.bind;
+                out.role = n.role || 'body';
+            }
+            if (n.type === 'image' && ++images > 1)
+                throw new Error('Only one illustration per composition');
+            if (n.type === 'icon') {
+                if (!n.icon || !['idea', 'check', 'chart', 'people', 'shield', 'arrow'].includes(n.icon))
+                    throw new Error('Invalid icon');
+                out.icon = n.icon;
+            }
+        }
+        return out;
+    }
+    const root = visit(value.root, 0);
+    if (Object.keys(fields).some(key => !seen.has(key)))
+        throw new Error('Composition omits content');
+    return { version: 1, root };
+}

package/dist/cjs/compositionScenes.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AUTHORED_COMPOSITIONS = exports.COMPOSITION_SCENES = void 0;
+exports.sceneRecipePreference = sceneRecipePreference;
+const both = ['presentation', 'social'];
+exports.COMPOSITION_SCENES = [
+    { id: 'brand-collection', kinds: ['features'], outputs: both },
+    { id: 'hero', kinds: ['paragraph'], outputs: both }, { id: 'chapter', kinds: ['paragraph'], outputs: ['presentation'] },
+    { id: 'statement', kinds: ['paragraph'], outputs: both }, { id: 'closing', kinds: ['paragraph'], outputs: both },
+    { id: 'product-launch', kinds: ['features'], outputs: both }, { id: 'feature-spotlight', kinds: ['features'], outputs: both },
+    { id: 'feature-overview', kinds: ['features'], outputs: both }, { id: 'benefits', kinds: ['features'], outputs: both },
+    { id: 'comparison', kinds: ['comparison'], outputs: both }, { id: 'before-after', kinds: ['comparison'], outputs: both },
+    { id: 'plan-options', kinds: ['comparison'], outputs: both }, { id: 'process', kinds: ['steps'], outputs: both },
+    { id: 'roadmap', kinds: ['steps'], outputs: both }, { id: 'tutorial', kinds: ['steps'], outputs: both },
+    { id: 'checklist', kinds: ['features'], outputs: both }, { id: 'metrics', kinds: ['chart'], outputs: both },
+    { id: 'trend', kinds: ['chart'], outputs: both }, { id: 'results', kinds: ['chart'], outputs: both },
+    { id: 'quotation', kinds: ['quote'], outputs: both }, { id: 'testimonial', kinds: ['quote'], outputs: both },
+    { id: 'code-example', kinds: ['code'], outputs: both }, { id: 'specifications', kinds: ['parameters'], outputs: both },
+    { id: 'pricing-details', kinds: ['parameters'], outputs: both }, { id: 'event-details', kinds: ['parameters'], outputs: both },
+    { id: 'recruitment-details', kinds: ['parameters'], outputs: both },
+    { id: 'product-demonstration', kinds: ['image'], outputs: both, requiresAsset: true },
+    { id: 'photograph', kinds: ['image'], outputs: both, requiresAsset: true },
+    ...['banner-hero', 'product-showcase', 'editorial-cover', 'image-campaign'].map(id => ({ id, kinds: ['image'], outputs: both, requiresAsset: true })),
+];
+exports.AUTHORED_COMPOSITIONS = [
+    { id: 'feature-focus', kind: 'features', min: 1, max: 1 },
+    { id: 'feature-bento', kind: 'features', min: 2, max: 6 },
+    { id: 'feature-index', kind: 'features', min: 2, max: 6 },
+    { id: 'steps-journey', kind: 'steps', min: 2, max: 6 },
+    { id: 'steps-ribbon', kind: 'steps', min: 2, max: 4 },
+    { id: 'comparison-panels', kind: 'comparison', min: 2, max: 3 },
+    { id: 'quote-editorial', kind: 'quote', min: 0, max: 0 },
+    { id: 'quote-poster', kind: 'quote', min: 0, max: 0 },
+    { id: 'code-editorial', kind: 'code', min: 0, max: 0 },
+    { id: 'parameter-ledger', kind: 'parameters', min: 1, max: 8 },
+    { id: 'parameter-cards', kind: 'parameters', min: 1, max: 4 },
+];
+/** Soft art-direction preferences; capacity and measured quality always remain mandatory. */
+function sceneRecipePreference(scene, recipeId) {
+    const preferred = {
+        'banner-hero': ['authored-image-banner'], 'product-showcase': ['authored-image-split'], 'editorial-cover': ['authored-image-editorial'], 'image-campaign': ['authored-image-campaign'],
+        hero: ['cover', 'semantic-hero-split'], chapter: ['section', 'semantic-hero-editorial'], statement: ['statement', 'semantic-hero-stack'], closing: ['closing'],
+        'product-launch': ['authored-feature-bento'], 'feature-spotlight': ['authored-feature-focus'], 'feature-overview': ['authored-feature-bento', 'three-column'], benefits: ['authored-feature-index'],
+        comparison: ['authored-comparison-panels'], 'before-after': ['before-after', 'semantic-comparison-split'], 'plan-options': ['authored-comparison-panels'],
+        process: ['authored-steps-ribbon'], roadmap: ['authored-steps-ribbon', 'roadmap'], tutorial: ['authored-steps-journey'], checklist: ['authored-feature-index', 'checklist'],
+        quotation: ['authored-quote-editorial'], testimonial: ['authored-quote-poster'],
+        'code-example': ['authored-code-editorial'], specifications: ['authored-parameter-ledger'],
+        'pricing-details': ['authored-parameter-cards'], 'event-details': ['authored-parameter-cards'], 'recruitment-details': ['authored-parameter-ledger'],
+    };
+    return scene && preferred[scene]?.some(id => recipeId === id || recipeId.startsWith(`${id}--`)) ? 6 : 0;
+}