@neatico/visual-core 0.14.3 → 0.14.64

package/dist/editorial.d.ts

@@ -1,4 +1,4 @@
-import { type ContentPage, type ContentPlan } from './content.js';
+import { type ContentPage, type ContentPlan } from "./content.js";
 /** Reading density, not just geometric fit. CJK occupies roughly twice Latin's width. */
 export declare const readingUnits: (text: string) => number;
 export declare function needsEditorialPagination(page: ContentPage): boolean;

package/dist/editorial.js

@@ -1,35 +1,91 @@
-import { contentBlockText } from './content.js';
+import { contentBlockText, } from "./content.js";
 /** Reading density, not just geometric fit. CJK occupies roughly twice Latin's width. */
-export const readingUnits = (text) => Array.from(text).reduce((n, c) => n + (/\s/.test(c) ? 0.2 : /[\u2e80-\u9fff\uac00-\ud7af\u3040-\u30ff]/u.test(c) ? 1 : 0.52), 0);
+export const readingUnits = (text) => Array.from(text).reduce((n, c) => n +
+    (/\s/.test(c)
+        ? 0.2
+        : /[\u2e80-\u9fff\uac00-\ud7af\u3040-\u30ff]/u.test(c)
+            ? 1
+            : 0.52), 0);
 export function needsEditorialPagination(page) {
-    if (page.scene === 'brand-collection')
+    if (page.scene === "brand-collection")
         return false;
-    const entries = page.blocks.flatMap(b => b.kind === 'features' || b.kind === 'steps' ? b.entries : []);
-    if (entries.length >= 3 && entries.some(e => readingUnits(e.description) > 65))
+    const entries = page.blocks.flatMap((b) => b.kind === "features" || b.kind === "steps" ? b.entries : []);
+    if (entries.length >= 3 &&
+        entries.some((e) => readingUnits(e.description) > 65))
         return true;
     const total = page.blocks.reduce((n, b) => n + contentBlockText(b).reduce((m, s) => m + readingUnits(s), 0), 0);
-    return total > 250 || page.blocks.some(b => b.kind === 'paragraph' ? readingUnits(b.text) > 165 : (b.kind === 'features' || b.kind === 'steps') && (b.entries.some(e => readingUnits(e.description) > 135) || (b.entries.length >= 3 && b.entries.some(e => readingUnits(e.description) > 65))));
+    return (total > 250 ||
+        page.blocks.some((b) => b.kind === "paragraph"
+            ? readingUnits(b.text) > 165
+            : (b.kind === "features" || b.kind === "steps") &&
+                (b.entries.some((e) => readingUnits(e.description) > 135) ||
+                    (b.entries.length >= 3 &&
+                        b.entries.some((e) => readingUnits(e.description) > 65)))));
 }
-const endings = { zh: '感谢聆听', en: 'Thank you', de: 'Vielen Dank', es: 'Gracias', fr: 'Merci', ja: 'ご清聴ありがとうございました', pt: 'Obrigado' };
+const endings = {
+    zh: "感谢聆听",
+    en: "Thank you",
+    de: "Vielen Dank",
+    es: "Gracias",
+    fr: "Merci",
+    ja: "ご清聴ありがとうございました",
+    pt: "Obrigado",
+};
 /** Structural bookends contain no invented customer claims or calls to action. */
 export function ensurePresentationBookends(plan) {
-    if (plan.kind !== 'presentation' || !plan.pages.length)
+    if (plan.kind !== "presentation" || !plan.pages.length)
         return plan;
-    const text = [plan.title, ...plan.pages.map(p => p.title)].join(' ');
-    const language = /[\u3040-\u30ff]/.test(text) ? 'ja' : /[\u3400-\u9fff]/.test(text) ? 'zh' : /\b(und|für|Einführung)\b/i.test(text) ? 'de' : /\b(pour|présentation|avec)\b/i.test(text) ? 'fr' : /\b(para|apresentação|com)\b/i.test(text) ? 'pt' : /\b(presentación|con|gracias)\b/i.test(text) ? 'es' : 'en';
-    const pages = plan.pages.map(p => ({ ...p, blocks: [...p.blocks] }));
-    const used = new Set(pages.flatMap(p => [p.id, ...p.blocks.map(b => b.id)]));
-    const id = (prefix) => { let s = prefix, i = 0; while (used.has(s))
-        s = `${prefix}-${++i}`; used.add(s); return s; };
-    const bookend = (purpose) => ({ id: id(`deck-${purpose}`), title: purpose === 'cover' ? plan.title : endings[language], purpose, scene: purpose === 'cover' ? 'hero' : 'closing', evidence: pages[0].evidence, blocks: [{ id: id(`deck-${purpose}-caption`), kind: 'paragraph', text: plan.title, evidence: pages[0].evidence }] });
-    if (pages[0].purpose !== 'cover')
-        pages.unshift(bookend('cover'));
+    const text = [plan.title, ...plan.pages.map((p) => p.title)].join(" ");
+    const language = /[\u3040-\u30ff]/.test(text)
+        ? "ja"
+        : /[\u3400-\u9fff]/.test(text)
+            ? "zh"
+            : /\b(und|für|Einführung)\b/i.test(text)
+                ? "de"
+                : /\b(pour|présentation|avec)\b/i.test(text)
+                    ? "fr"
+                    : /\b(para|apresentação|com)\b/i.test(text)
+                        ? "pt"
+                        : /\b(presentación|con|gracias)\b/i.test(text)
+                            ? "es"
+                            : "en";
+    const pages = plan.pages.map((p) => ({ ...p, blocks: [...p.blocks] }));
+    const used = new Set(pages.flatMap((p) => [p.id, ...p.blocks.map((b) => b.id)]));
+    const id = (prefix) => {
+        let s = prefix, i = 0;
+        while (used.has(s))
+            s = `${prefix}-${++i}`;
+        used.add(s);
+        return s;
+    };
+    const bookend = (purpose) => ({
+        id: id(`deck-${purpose}`),
+        title: purpose === "cover" ? plan.title : endings[language],
+        purpose,
+        scene: purpose === "cover" ? "hero" : "closing",
+        evidence: pages[0].evidence,
+        blocks: [
+            {
+                id: id(`deck-${purpose}-caption`),
+                kind: "paragraph",
+                text: plan.title,
+                evidence: pages[0].evidence,
+            },
+        ],
+    });
+    if (pages[0].purpose !== "cover")
+        pages.unshift(bookend("cover"));
     const last = pages[pages.length - 1];
     // Evidence and long explanations remain content slides, never masquerade as a closing.
-    if (last.purpose !== 'conclude' || last.scene === 'brand-collection' || last.blocks.some(b => b.kind !== 'paragraph') || last.blocks.reduce((n, b) => n + contentBlockText(b).join('').length, 0) > 120 || /行业认可|客户|customers|trusted by/i.test(last.title)) {
-        if (last.purpose === 'conclude')
-            last.purpose = 'evidence';
-        pages.push(bookend('conclude'));
+    if (last.purpose !== "conclude" ||
+        last.scene === "brand-collection" ||
+        last.blocks.some((b) => b.kind !== "paragraph") ||
+        last.blocks.reduce((n, b) => n + contentBlockText(b).join("").length, 0) >
+            120 ||
+        /行业认可|客户|customers|trusted by/i.test(last.title)) {
+        if (last.purpose === "conclude")
+            last.purpose = "evidence";
+        pages.push(bookend("conclude"));
     }
     return { ...plan, pages };
 }

package/dist/fontCatalog.d.ts

@@ -1,6 +1,6 @@
 export interface FontFamily {
     family: string;
-    category: 'sans' | 'serif' | 'display' | 'mono';
+    category: "sans" | "serif" | "display" | "mono";
     scripts: readonly string[];
     weights: readonly number[];
 }

package/dist/fontCatalog.js

@@ -1,36 +1,94 @@
-const entry = (family, category, scripts = ['latin'], weights = [400, 700]) => ({ family, category, scripts, weights });
+const entry = (family, category, scripts = ["latin"], weights = [400, 700]) => ({ family, category, scripts, weights });
 /** Curated Google Fonts families; request only their declared, supported weights. */
 export const GOOGLE_FONT_CATALOG = [
-    ...['Inter', 'Roboto', 'Montserrat', 'Manrope', 'DM Sans', 'Lato', 'Open Sans', 'Source Sans 3', 'Work Sans', 'Nunito Sans', 'IBM Plex Sans'].map(f => entry(f, 'sans')),
-    ...['Lora', 'Merriweather', 'Libre Baskerville', 'Source Serif 4', 'Playfair Display', 'PT Serif'].map(f => entry(f, 'serif')),
-    ...['Space Grotesk', 'Oswald', 'Bebas Neue'].map(f => entry(f, 'display', ['latin'], f === 'Bebas Neue' ? [400] : [400, 700])),
-    ...['JetBrains Mono', 'IBM Plex Mono', 'Fira Code', 'Source Code Pro'].map(f => entry(f, 'mono')),
-    entry('Noto Sans SC', 'sans', ['zh']), entry('Noto Serif SC', 'serif', ['zh']), entry('ZCOOL XiaoWei', 'display', ['zh'], [400]), entry('Ma Shan Zheng', 'display', ['zh'], [400]),
-    entry('Noto Sans TC', 'sans', ['zh-Hant']), entry('Noto Serif TC', 'serif', ['zh-Hant']),
-    entry('Noto Sans JP', 'sans', ['ja']), entry('Noto Serif JP', 'serif', ['ja']), entry('M PLUS Rounded 1c', 'sans', ['ja']),
-    entry('Noto Sans KR', 'sans', ['ko']), entry('Noto Serif KR', 'serif', ['ko']),
-    entry('Noto Sans Arabic', 'sans', ['ar']), entry('Noto Sans Devanagari', 'sans', ['hi']),
+    ...[
+        "Inter",
+        "Roboto",
+        "Montserrat",
+        "Manrope",
+        "DM Sans",
+        "Lato",
+        "Open Sans",
+        "Source Sans 3",
+        "Work Sans",
+        "Nunito Sans",
+        "IBM Plex Sans",
+    ].map((f) => entry(f, "sans")),
+    ...[
+        "Lora",
+        "Merriweather",
+        "Libre Baskerville",
+        "Source Serif 4",
+        "Playfair Display",
+        "PT Serif",
+    ].map((f) => entry(f, "serif")),
+    entry("Instrument Serif", "serif", ["latin"], [400]),
+    ...["Space Grotesk", "Oswald", "Bebas Neue"].map((f) => entry(f, "display", ["latin"], f === "Bebas Neue" ? [400] : [400, 700])),
+    ...["JetBrains Mono", "IBM Plex Mono", "Fira Code", "Source Code Pro"].map((f) => entry(f, "mono")),
+    entry("Noto Sans SC", "sans", ["zh"]),
+    entry("Noto Serif SC", "serif", ["zh"]),
+    entry("ZCOOL XiaoWei", "display", ["zh"], [400]),
+    entry("Ma Shan Zheng", "display", ["zh"], [400]),
+    entry("Noto Sans TC", "sans", ["zh-Hant"]),
+    entry("Noto Serif TC", "serif", ["zh-Hant"]),
+    entry("Noto Sans JP", "sans", ["ja"]),
+    entry("Noto Serif JP", "serif", ["ja"]),
+    entry("M PLUS Rounded 1c", "sans", ["ja"]),
+    entry("Noto Sans KR", "sans", ["ko"]),
+    entry("Noto Serif KR", "serif", ["ko"]),
+    entry("Noto Sans Arabic", "sans", ["ar"]),
+    entry("Noto Sans Devanagari", "sans", ["hi"]),
+    entry("Noto Serif Devanagari", "serif", ["hi"]),
+    entry("Noto Sans Thai", "sans", ["th"]),
+    entry("Noto Serif Thai", "serif", ["th"]),
 ];
-export function contentScript(text, locale = 'en') {
+export function contentScript(text, locale = "en") {
     if (/[\u3040-\u30ff]/u.test(text))
-        return 'ja';
+        return "ja";
     if (/[\uac00-\ud7af]/u.test(text))
-        return 'ko';
+        return "ko";
     if (/[\u0600-\u06ff]/u.test(text))
-        return 'ar';
+        return "ar";
     if (/[\u0900-\u097f]/u.test(text))
-        return 'hi';
+        return "hi";
+    if (/[\u0e00-\u0e7f]/u.test(text))
+        return "th";
     if (/[\u3400-\u9fff]/u.test(text))
-        return /TW|HK|Hant/i.test(locale) ? 'zh-Hant' : 'zh';
+        return /^ja/i.test(locale)
+            ? "ja"
+            : /^ko/i.test(locale)
+                ? "ko"
+                : /TW|HK|Hant/i.test(locale)
+                    ? "zh-Hant"
+                    : "zh";
     if (/^zh/i.test(locale))
-        return /TW|HK|Hant/i.test(locale) ? 'zh-Hant' : 'zh';
-    return /^(ja|ko|ar|hi)/.exec(locale)?.[1] || 'latin';
+        return /TW|HK|Hant/i.test(locale) ? "zh-Hant" : "zh";
+    return /^(ja|ko|ar|hi|th)/.exec(locale)?.[1] || "latin";
 }
-export function recommendedFonts(locale, text = '') { const script = contentScript(text, locale); return [...GOOGLE_FONT_CATALOG].sort((a, b) => Number(b.scripts.includes(script)) - Number(a.scripts.includes(script))); }
-export function languageFont(text, preferred, locale = 'en') {
+export function recommendedFonts(locale, text = "") {
     const script = contentScript(text, locale);
-    if (script === 'latin')
+    return [...GOOGLE_FONT_CATALOG].sort((a, b) => Number(b.scripts.includes(script)) - Number(a.scripts.includes(script)));
+}
+export function languageFont(text, preferred, locale = "en") {
+    const script = contentScript(text, locale);
+    if (script === "latin")
+        return preferred;
+    const selected = GOOGLE_FONT_CATALOG.find((font) => font.family === preferred);
+    if (selected?.scripts.includes(script))
+        return preferred;
+    if (!selected &&
+        ![
+            "Arial",
+            "Helvetica",
+            "Georgia",
+            "Times New Roman",
+            "Courier New",
+            "sans-serif",
+            "serif",
+            "monospace",
+        ].includes(preferred))
         return preferred;
-    const serif = /serif|Georgia|Lora|Baskerville|Merriweather|Playfair/i.test(preferred) && !/sans/i.test(preferred);
-    return GOOGLE_FONT_CATALOG.find(f => f.scripts.includes(script) && f.category === (serif ? 'serif' : 'sans'))?.family || preferred;
+    const serif = /serif|Georgia|Lora|Baskerville|Merriweather|Playfair/i.test(preferred) &&
+        !/sans/i.test(preferred);
+    return (GOOGLE_FONT_CATALOG.find((f) => f.scripts.includes(script) && f.category === (serif ? "serif" : "sans"))?.family || preferred);
 }

package/dist/formalCompositions.d.ts

@@ -0,0 +1,26 @@
+import { type DesignRecipe } from './designSystem.js';
+import { type RecipeParameterContract, type CompositionKind } from './recipeParameters.js';
+import type { SemanticKind } from './content.js';
+export interface FormalComposition extends RecipeParameterContract {
+    displayNumber: string;
+    aspectRatios: {
+        min: number;
+        max: number;
+    };
+    recipe?: DesignRecipe;
+}
+/** Structural reference contracts shared with the product's existing renderers.
+ * Colorways and historical aliases remain outside active discovery.
+ */
+export declare const FORMAL_REFERENCE_COMPOSITIONS: readonly {
+    id: string;
+    reference: number;
+    layout: string;
+    accepts: readonly SemanticKind[];
+}[];
+/** Matches /dev/compositions/all: 161 default previews plus two landscape-only
+ * reference entries. Output capabilities overlap and must never be summed.
+ */
+export declare const FORMAL_COMPOSITIONS: readonly FormalComposition[];
+/** Only output, ratio, and explicit IDs are hard gates; semantic fit is scored. */
+export declare function applicableCompositions(kind: CompositionKind, ratio: number, id?: string): FormalComposition[];

package/dist/formalCompositions.js

@@ -0,0 +1,116 @@
+import { compositionUseCase } from './compositionUseCases.js';
+import { nativeSocialParameterContract } from './nativeSocialParameters.js';
+import { DESIGN_RECIPES } from './designSystem.js';
+import { SOCIAL_LAYOUT_CATALOG } from './socialLayouts.js';
+import { recipeParameterContract } from './recipeParameters.js';
+import { SEMANTIC_DISPLAY_NUMBERS, SOCIAL_DISPLAY_NUMBERS } from './compositionNumbers.js';
+const both = ['presentation', 'social'];
+const semantic = (id, accepts, minEntries = 0, maxEntries = 12, requiresImage = false) => ({ id, renderer: 'semantic', kind: 'social', family: id, accepts, minEntries, maxEntries, requiresImage });
+function define(recipe, kinds, id, displayNumber, min = .25, max = 4) {
+    return { ...recipeParameterContract(recipe, kinds), semanticDescription: compositionUseCase(recipe.id), id, displayNumber, aspectRatios: { min, max }, recipe };
+}
+/** Structural reference contracts shared with the product's existing renderers.
+ * Colorways and historical aliases remain outside active discovery.
+ */
+export const FORMAL_REFERENCE_COMPOSITIONS = [
+    { id: 'authored-reference-photo', reference: 1, layout: 'authored-photo-editorial', accepts: ['image', 'paragraph'] },
+    { id: 'authored-reference-manifesto', reference: 2, layout: 'authored-type-manifesto', accepts: ['paragraph'] },
+    { id: 'authored-reference-journey', reference: 3, layout: 'authored-editorial-flow', accepts: ['steps'] },
+    { id: 'authored-reference-vision', reference: 4, layout: 'authored-editorial-features', accepts: ['features'] },
+    { id: 'authored-reference-matrix', reference: 5, layout: 'authored-editorial-matrix', accepts: ['comparison', 'paragraph'] },
+    { id: 'authored-reference-diagonal', reference: 6, layout: 'authored-diagonal-cover', accepts: ['paragraph'] },
+    { id: 'authored-reference-list', reference: 8, layout: 'authored-editorial-index', accepts: ['features'] },
+    { id: 'authored-reference-story', reference: 11, layout: 'authored-visual-poster', accepts: ['image', 'paragraph', 'features'] },
+    { id: 'authored-reference-sustainable', reference: 13, layout: 'authored-editorial-metrics', accepts: ['parameters'] },
+    { id: 'authored-reference-code', reference: 14, layout: 'authored-code-panel', accepts: ['code'] },
+    { id: 'authored-reference-bars', reference: 18, layout: 'authored-editorial-bars', accepts: ['chart'] },
+    { id: 'authored-reference-share', reference: 19, layout: 'authored-editorial-donut', accepts: ['chart'] },
+    { id: 'authored-reference-opinion', reference: 20, layout: 'authored-editorial-quote', accepts: ['quote'] },
+    { id: 'authored-reference-comparison', reference: 22, layout: 'authored-editorial-comparison', accepts: ['comparison'] },
+    { id: 'authored-reference-faq', reference: 23, layout: 'authored-editorial-faq', accepts: ['features'] },
+    { id: 'authored-reference-trend', reference: 25, layout: 'authored-editorial-trend', accepts: ['chart'] },
+];
+const semanticRecipes = DESIGN_RECIPES.filter(recipe => recipe.renderer === 'semantic');
+const uniqueSemantic = semanticRecipes.filter((recipe, index) => semanticRecipes.findIndex(other => other.id === recipe.id) === index);
+const campaignDefinitions = [
+    ['ledger-chart', ['parameters', 'chart'], 2, 6, false, true],
+    ['detail-sidebar', ['paragraph', 'parameters'], 1, 3, false, true],
+    ['technical-log', ['code', 'paragraph'], 0, 12, false, false],
+    ['architecture-stack', ['steps', 'paragraph'], 2, 4, false, false],
+    ['speaker-spotlight', ['quote', 'parameters'], 1, 6, true, false],
+    ['speaker-lineup', ['quote', 'parameters'], 1, 6, true, false],
+];
+const founderDefinitions = [
+    ['authored-mechanism-flow', ['features', 'steps', 'paragraph'], 2, 4],
+    ['authored-reference-capability-map', ['features', 'paragraph'], 2, 4],
+    ['authored-founder-timeline', ['steps', 'paragraph'], 2, 4],
+    ['authored-founder-comparison', ['comparison', 'paragraph'], 2, 2],
+];
+const articleKinds = ['features', 'process', 'comparison', 'summary', 'checklist', 'faq', 'chart'];
+const articleAccepts = { features: ['features', 'paragraph'], process: ['steps', 'paragraph'], comparison: ['comparison', 'paragraph'], summary: ['paragraph', 'features'], checklist: ['features', 'paragraph'], faq: ['features', 'paragraph'], chart: ['chart', 'paragraph'] };
+function article(id, kind, variant) {
+    const cover = kind === 'cover';
+    const recipe = semantic(id, cover ? ['paragraph', 'features', 'image'] : articleAccepts[kind], 0, kind === 'chart' ? 12 : 3);
+    const number = cover ? variant + 1 : kind === 'features' && variant >= 3 ? 22 + variant : kind === 'process' && variant === 3 ? 33 : 4 + articleKinds.indexOf(kind) * 3 + variant;
+    const definition = define(recipe, [cover ? 'article-cover' : 'article-illustration'], id, `A${String(number).padStart(3, '0')}`, .5, 2.4);
+    // A cover is a headline, a short deck and its authored hero. It is not a
+    // miniature article: the original source remains in the candidate pool.
+    const coverSchema = { type: 'object', additionalProperties: false, required: ['title', 'blocks'], properties: {
+            title: { type: 'string', minLength: 1, maxLength: 72, description: 'A concise editorial headline, preferably four to eight words.' },
+            blocks: { type: 'array', minItems: 1, maxItems: 1, items: { type: 'object', additionalProperties: false, required: ['id', 'kind', 'text', 'evidence'], properties: {
+                        id: { type: 'string', minLength: 1, maxLength: 80 }, kind: { const: 'paragraph' }, text: { type: 'string', minLength: 1, maxLength: 140, description: 'One concise supporting sentence. Summarize the topic; do not repeat the full article or enumerate every feature.' },
+                        evidence: { type: 'array', minItems: 1, maxItems: 32, items: { type: 'object', additionalProperties: false, required: ['sourceId'], properties: { sourceId: { type: 'string', maxLength: 160 }, quote: { type: 'string', maxLength: 2000 } } } },
+                    } } },
+        } };
+    // The optional hero preserves compatibility with saved paragraph-only pools.
+    // New requests can reference a real asset; missing assets retain native artwork.
+    const coverWithHero = { ...coverSchema, properties: { ...coverSchema.properties, blocks: { ...coverSchema.properties.blocks, maxItems: 2,
+                description: 'One supporting paragraph and, when imagery helps explain the topic, one image hero. Use an available asset ID or a missing image request; never invent a photo URL.',
+                items: [coverSchema.properties.blocks.items, { type: 'object', additionalProperties: false, required: ['id', 'kind', 'sourceId', 'alt', 'treatment', 'status', 'evidence'], properties: {
+                            id: { type: 'string', minLength: 1, maxLength: 80 }, kind: { const: 'image' }, sourceId: { type: 'string', maxLength: 160 },
+                            alt: { type: 'string', minLength: 1, maxLength: 300, description: 'A concise description of the image subject, grounded in the article topic.' },
+                            treatment: { enum: ['photograph', 'diagram', 'screenshot'] }, status: { enum: ['available', 'missing'] }, assetId: { type: 'string', maxLength: 200 },
+                            evidence: coverSchema.properties.blocks.items.properties.evidence,
+                        } }],
+            } } };
+    const illustrationSchema = JSON.parse(JSON.stringify(definition.parameterSchema));
+    if (!cover) {
+        const primaryKind = kind === 'summary' ? 'features' : articleAccepts[kind][0];
+        const blocks = illustrationSchema.properties.blocks;
+        const primary = blocks.items.find((block) => block.properties.kind.const === primaryKind);
+        blocks.items = [primary];
+        blocks.minItems = 1;
+        blocks.maxItems = 1;
+        if (kind === 'faq')
+            primary.properties.entries.items.properties.title.pattern = '^.+[?？]$';
+    }
+    const coverDirections = ['An editorial document sculpture with layered planes and a strong headline.', 'A connected constellation with a single focal object and an editorial headline.', 'An architectural archive silhouette balanced against expressive editorial typography.'];
+    return { ...definition, ...(cover ? { parameterSchema: coverWithHero, capacity: { minEntries: 0, maxEntries: 0, requiresImage: false }, semanticDescription: coverDirections[variant] } : { parameterSchema: illustrationSchema }), recipe: undefined, rendererKey: `article-${kind}:${variant}`,
+        semanticDescription: compositionUseCase(id) + (cover ? ' ' + coverDirections[variant] : '') };
+}
+/** Matches /dev/compositions/all: 161 default previews plus two landscape-only
+ * reference entries. Output capabilities overlap and must never be summed.
+ */
+export const FORMAL_COMPOSITIONS = [
+    ...campaignDefinitions.map(([id, accepts, min, max, image, landscape], index) => define(semantic(`authored-reference-${id}`, accepts, min, max, image), landscape ? ['presentation'] : both, `new-reference:${id}`, `N${index + 1}`, landscape ? 1.4 : .25)),
+    define(semantic('authored-event-poster', ['parameters', 'paragraph'], 1, 6), ['social'], 'event:provider', 'E1'),
+    define(semantic('authored-image-triptych', ['paragraph', 'features', 'image'], 3, 3, true), ['social'], 'campaign:triptych', 'C1', .5, 2),
+    ...FORMAL_REFERENCE_COMPOSITIONS.map(spec => define(semantic(spec.id, spec.accepts, 0, 12, spec.accepts.includes('image')), both, `reference:${spec.id}`, `R${String(spec.reference).padStart(2, '0')}`)),
+    ...SOCIAL_LAYOUT_CATALOG.map(preset => {
+        const recipe = DESIGN_RECIPES.find(item => item.id === preset.id && item.kind === 'social');
+        return { ...define({ ...recipe, renderer: 'catalog' }, ['social'], `social:${preset.id}`, SOCIAL_DISPLAY_NUMBERS[preset.id], .5, 2.4), ...nativeSocialParameterContract(preset.id) };
+    }),
+    ...uniqueSemantic.map(recipe => define(recipe, semanticRecipes.filter(other => other.id === recipe.id).map(other => other.kind), `semantic:${recipe.kind}:${recipe.id}`, SEMANTIC_DISPLAY_NUMBERS[`semantic:${recipe.kind}:${recipe.id}`])),
+    ...founderDefinitions.map(([id, accepts, min, max], index) => define(semantic(id, accepts, min, max), ['social'], `semantic:social:${id}`, `F${index + 1}`, 1.3)),
+    ...[0, 1, 2].flatMap(variant => [article(`article-cover-${variant}`, 'cover', variant), ...articleKinds.map(kind => article(`article-${kind}-${variant}`, kind, variant))]),
+    ...[3, 4, 5, 6, 7, 8, 9, 10].map(variant => article(`article-features-${variant}`, 'features', variant)),
+    article('article-process-3', 'process', 3),
+];
+/** Only output, ratio, and explicit IDs are hard gates; semantic fit is scored. */
+export function applicableCompositions(kind, ratio, id) {
+    if (!Number.isFinite(ratio) || ratio <= 0)
+        throw new Error('COMPOSITION_INVALID_RATIO');
+    if (id && !FORMAL_COMPOSITIONS.some(item => item.id === id))
+        throw new Error('COMPOSITION_UNKNOWN_ID');
+    return FORMAL_COMPOSITIONS.filter(item => item.supportedKinds.includes(kind) && ratio >= item.aspectRatios.min && ratio <= item.aspectRatios.max && (!id || item.id === id));
+}

package/dist/index.d.ts

@@ -13,3 +13,13 @@ export * from "./designBlueprint.js";
 export * from './compositionScenes.js';
 export * from './editorial.js';
 export * from './fontCatalog.js';
+export * from './candidateRanking.js';
+export * from './styleManifest.js';
+export * from './recipeParameters.js';
+export * from './formalCompositions.js';
+export * from './contentBrief.js';
+export * from "./nativeSocialParameters.js";
+export * from "./compositionUseCases.js";
+export { compositionParameterDefaults } from './parameterDefaults.js';
+export { SOCIAL_DISPLAY_NUMBERS } from './compositionNumbers.js';
+export * from './textPresentation.js';

package/dist/index.js

@@ -13,3 +13,13 @@ export * from "./designBlueprint.js";
 export * from './compositionScenes.js';
 export * from './editorial.js';
 export * from './fontCatalog.js';
+export * from './candidateRanking.js';
+export * from './styleManifest.js';
+export * from './recipeParameters.js';
+export * from './formalCompositions.js';
+export * from './contentBrief.js';
+export * from "./nativeSocialParameters.js";
+export * from "./compositionUseCases.js";
+export { compositionParameterDefaults } from './parameterDefaults.js';
+export { SOCIAL_DISPLAY_NUMBERS } from './compositionNumbers.js';
+export * from './textPresentation.js';

package/dist/layoutContracts.d.ts

@@ -1,6 +1,6 @@
 export interface LayoutContract {
     id: string;
-    kind: 'presentation' | 'social';
+    kind: "presentation" | "social";
     semantic: string;
     minItems: number;
     maxItems: number;
@@ -10,6 +10,6 @@ export interface LayoutContract {
 }
 /** Eligibility is a first filter, never a substitute for measured fit. */
 export declare const LAYOUT_CONTRACTS: readonly LayoutContract[];
-export declare function eligibleLayouts(kind: LayoutContract['kind'], content: Record<string, unknown>, ratio: number): LayoutContract[];
+export declare function eligibleLayouts(kind: LayoutContract["kind"], content: Record<string, unknown>, ratio: number): LayoutContract[];
 /** Requested intent, same semantic scene, then general-purpose structures. */
-export declare function layoutCandidates(kind: LayoutContract['kind'], requested: string, content: Record<string, unknown>, ratio: number, limit?: number): string[];
+export declare function layoutCandidates(kind: LayoutContract["kind"], requested: string, content: Record<string, unknown>, ratio: number, limit?: number): string[];

package/dist/layoutContracts.js

@@ -1,22 +1,68 @@
-import { PRESENTATION_LAYOUT_IDS } from './layouts.js';
-import { SOCIAL_LAYOUT_CATALOG } from './socialLayouts.js';
-const textOnly = new Set(['cover', 'section', 'statement', 'quote', 'closing', 'image-full', 'og-cover', 'gradient-cover', 'bold-diagonal-cover', 'split-cover', 'block-banner', 'video-cover', 'magazine-pull-quote']);
-const pair = new Set(['comparison', 'two-column', 'myth', 'problem-solution', 'before-after', 'split-bar-compare']);
+import { SOCIAL_LAYOUT_CATALOG } from "./socialLayouts.js";
+const textOnly = new Set([
+    "cover",
+    "section",
+    "statement",
+    "quote",
+    "closing",
+    "image-full",
+    "og-cover",
+    "gradient-cover",
+    "bold-diagonal-cover",
+    "split-cover",
+    "block-banner",
+    "video-cover",
+    "magazine-pull-quote",
+]);
+const pair = new Set([
+    "comparison",
+    "two-column",
+    "myth",
+    "problem-solution",
+    "before-after",
+    "split-bar-compare",
+]);
 /** Eligibility is a first filter, never a substitute for measured fit. */
 export const LAYOUT_CONTRACTS = [
-    ...PRESENTATION_LAYOUT_IDS.map(id => ({ id, kind: 'presentation', semantic: pair.has(id) ? 'comparison' : textOnly.has(id) ? 'editorial' : id, minItems: pair.has(id) ? 2 : 0, maxItems: textOnly.has(id) ? 0 : pair.has(id) ? 2 : 4, minRatio: 16 / 9, maxRatio: 16 / 9, required: ['title'] })),
-    ...SOCIAL_LAYOUT_CATALOG.map(({ id, scene }) => ({ id, kind: 'social', semantic: scene, minItems: pair.has(id) ? 2 : 0, maxItems: textOnly.has(id) ? 0 : pair.has(id) ? 2 : id === 'course-syllabus' ? 15 : 6, minRatio: .25, maxRatio: 4, required: ['headline', ...(['pricing', 'metric'].includes(scene) ? ['value'] : [])] })),
+    ...SOCIAL_LAYOUT_CATALOG.map(({ id, scene }) => ({
+        id,
+        kind: "social",
+        semantic: scene,
+        minItems: pair.has(id) ? 2 : 0,
+        maxItems: textOnly.has(id) ? 0 : pair.has(id) ? 2 : 6,
+        minRatio: 0.25,
+        maxRatio: 4,
+        required: [
+            "headline",
+            ...(["pricing", "metric"].includes(scene) ? ["value"] : []),
+        ],
+    })),
 ];
 export function eligibleLayouts(kind, content, ratio) {
     const count = Array.isArray(content.items) ? content.items.length : 0;
-    return LAYOUT_CONTRACTS.filter(layout => layout.kind === kind && ratio >= layout.minRatio - 1e-6 && ratio <= layout.maxRatio + 1e-6 && count >= layout.minItems && count <= layout.maxItems && layout.required.every(key => typeof content[key] === 'string' && String(content[key]).trim()));
+    return LAYOUT_CONTRACTS.filter((layout) => layout.kind === kind &&
+        ratio >= layout.minRatio - 1e-6 &&
+        ratio <= layout.maxRatio + 1e-6 &&
+        count >= layout.minItems &&
+        count <= layout.maxItems &&
+        layout.required.every((key) => typeof content[key] === "string" && String(content[key]).trim()));
 }
 /** Requested intent, same semantic scene, then general-purpose structures. */
 export function layoutCandidates(kind, requested, content, ratio, limit = 8) {
     const eligible = eligibleLayouts(kind, content, ratio);
-    const selected = LAYOUT_CONTRACTS.find(layout => layout.kind === kind && layout.id === requested);
-    const fallback = kind === 'presentation' ? ['cards', 'two-column', 'bullets', 'table', 'agenda', 'statement'] : ['report', 'checklist', 'steps', 'bento', 'editorial', 'story'];
-    const order = [requested, ...eligible.filter(layout => layout.semantic === (content.scene || selected?.semantic)).map(layout => layout.id), ...fallback];
-    const allowed = new Set(eligible.map(layout => layout.id));
-    return [...new Set(order)].filter(id => allowed.has(id)).slice(0, Math.max(1, Math.min(16, limit)));
+    const selected = LAYOUT_CONTRACTS.find((layout) => layout.kind === kind && layout.id === requested);
+    const fallback = kind === "presentation"
+        ? ["cards", "two-column", "bullets", "table", "agenda", "statement"]
+        : ["report", "checklist", "steps", "bento", "editorial", "story"];
+    const order = [
+        requested,
+        ...eligible
+            .filter((layout) => layout.semantic === (content.scene || selected?.semantic))
+            .map((layout) => layout.id),
+        ...fallback,
+    ];
+    const allowed = new Set(eligible.map((layout) => layout.id));
+    return [...new Set(order)]
+        .filter((id) => allowed.has(id))
+        .slice(0, Math.max(1, Math.min(16, limit)));
 }

package/dist/layouts.d.ts

@@ -1,2 +1,2 @@
-/** Shared stable IDs for authored presentation renderers. */
-export declare const PRESENTATION_LAYOUT_IDS: readonly ["cover", "agenda", "section", "statement", "bullets", "two-column", "comparison", "three-column", "process", "timeline", "metrics", "quote", "image-left", "image-right", "image-full", "closing", "cards", "checklist", "roadmap", "team", "pricing", "faq", "swot", "scorecard", "bar-chart", "funnel", "table", "problem-solution", "case-study", "architecture", "risk", "action-plan", "usage-breakdown", "organization", "editorial-quote", "research-highlight", "product-showcase", "split-bar-compare", "benchmark-bars", "block-banner", "progress-roadmap", "fan-deck", "contents-index", "contents-chapters", "contents-grid", "definition-card", "topic-branches", "radial-mindmap", "tips-card", "code-snippet", "series-carousel", "reflection-card", "video-cover", "digest-card", "chat-preview", "recommendation-feed", "before-after", "course-syllabus", "concept-explainer", "persona-question", "nutrient-symptom-grid", "milestone-history", "release-notes", "product-listing", "flash-sale", "event-banner", "startup-journey", "vision-goals", "tips-grid", "experiment-report", "leaderboard", "win-journey", "device-price-promo", "mega-sale-typographic", "illustration-process", "glass-neon-sale", "free-trial-hero", "feature-chip-hero", "event-speaker-card", "corporate-hero", "release-version-hero", "og-cover", "gradient-cover", "bold-diagonal-cover", "split-cover", "article-feed-card", "article-summary-card", "paragraph-summary-card", "summary-card-stack", "article-repost-card", "article-core-digest", "product-thread-mockup", "agent-notification", "angled-ui-launch", "repo-card", "magazine-pull-quote", "question-answer-quote"];
+/** Content intents for structured presentations; not a separate renderer catalog. */
+export declare const PRESENTATION_LAYOUT_IDS: readonly ["cover", "section", "statement", "cards", "process", "comparison", "bar-chart", "quote", "table", "closing"];