@neatico/visual-core 0.14.2 → 0.14.26

package/dist/composition.js

@@ -1,18 +1,29 @@
 export const 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.`;
 export function compositionFields(value) {
     const fields = {};
-    for (const key of ['title', 'headline', 'body', 'eyebrow', 'cta', 'value', 'attribution'])
-        if (typeof value[key] === 'string' && value[key].trim())
+    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;
-        } });
+        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;
 }
 export function validateComposition(raw, fields) {
@@ -20,44 +31,59 @@ export function validateComposition(raw, fields) {
     let count = 0, images = 0;
     const seen = new Set();
     if (!value || value.version !== 1)
-        throw new Error('Unsupported composition');
+        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));
+        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 < 0.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');
+                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';
+                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');
+            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');
+    if (Object.keys(fields).some((key) => !seen.has(key)))
+        throw new Error("Composition omits content");
     return { version: 1, root };
 }

package/dist/compositionScenes.d.ts

@@ -1,11 +1,11 @@
-import type { SemanticKind } from './content.js';
+import type { SemanticKind } from "./content.js";
 /** Product scenes describe user intent; recipes describe an executable composition.
  * Multiple scenes deliberately reuse a recipe. Scene count is not design count.
  */
 export interface CompositionScene {
     id: string;
     kinds: readonly SemanticKind[];
-    outputs: readonly ('presentation' | 'social')[];
+    outputs: readonly ("presentation" | "social")[];
     requiresAsset?: boolean;
 }
 export declare const COMPOSITION_SCENES: readonly CompositionScene[];

package/dist/compositionScenes.js

@@ -1,47 +1,100 @@
-const both = ['presentation', 'social'];
+const both = ["presentation", "social"];
 export const 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 })),
+    { id: "menu-details", kinds: ["parameters"], outputs: both },
+    { id: "travel-details", kinds: ["parameters"], outputs: both },
+    { id: "offer-details", kinds: ["parameters"], outputs: both },
+    { id: "questions", kinds: ["features"], outputs: both },
+    { id: "case-study", kinds: ["features"], outputs: both },
+    { 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,
+    })),
 ];
 export const 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 },
+    { 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. */
 export 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'],
+        "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;
+    return scene &&
+        preferred[scene]?.some((id) => recipeId === id || recipeId.startsWith(`${id}--`))
+        ? 6
+        : 0;
 }

package/dist/content.d.ts

@@ -1,5 +1,5 @@
 /** Source-backed content, independent of layout and editor primitives. */
-export type SourceKind = 'text' | 'code' | 'image-reference';
+export type SourceKind = "text" | "code" | "image-reference";
 export interface SourceSegment {
     id: string;
     kind: SourceKind;
@@ -17,73 +17,108 @@ export interface Evidence {
     sourceId: string;
     quote?: string;
 }
-export type SemanticKind = 'paragraph' | 'steps' | 'features' | 'comparison' | 'code' | 'parameters' | 'quote' | 'chart' | 'image';
+export type SemanticKind = "paragraph" | "steps" | "features" | "comparison" | "code" | "parameters" | "quote" | "chart" | "image";
+export interface ComparisonColumn {
+    title: string;
+    points: string[];
+    price?: string;
+    values?: string[];
+    statuses?: ("included" | "excluded" | "partial" | "unknown")[];
+}
 interface BlockBase {
     id: string;
     evidence: Evidence[];
 }
 export type ContentBlock = BlockBase & ({
-    kind: 'paragraph';
+    kind: "paragraph";
     text: string;
     heading?: string;
     level?: 2 | 3;
 } | {
-    kind: 'steps' | 'features';
+    kind: "steps" | "features";
     entries: {
         title: string;
         description: string;
+        icon?: string;
+        illustration?: string;
     }[];
 } | {
-    kind: 'comparison';
-    columns: {
-        title: string;
-        points: string[];
-    }[];
+    kind: "comparison";
+    columns: ComparisonColumn[];
 } | {
-    kind: 'code';
+    kind: "code";
     sourceId: string;
     language: string;
     code: string;
 } | {
-    kind: 'parameters';
+    kind: "parameters";
     rows: {
         name: string;
         value: string;
         description: string;
     }[];
 } | {
-    kind: 'quote';
+    kind: "quote";
     text: string;
     attribution: string;
+    avatarAssetId?: string;
+    role?: string;
 } | {
-    kind: 'chart';
-    chart: 'bar' | 'line';
+    kind: "chart";
+    chart: "bar" | "line";
     unit: string;
     values: {
         label: string;
         value: number;
     }[];
 } | {
-    kind: 'image';
+    kind: "image";
     sourceId: string;
     alt: string;
-    treatment: 'screenshot' | 'photograph' | 'diagram';
-    status: 'missing' | 'available';
+    treatment: "screenshot" | "photograph" | "diagram";
+    status: "missing" | "available";
     assetId?: string;
 });
+export interface PublicationInfo {
+    tags?: string[];
+    author?: {
+        name: string;
+        role?: string;
+        avatarAssetId?: string;
+    };
+    metrics?: {
+        label: string;
+        value: string;
+    }[];
+    date?: string;
+    source?: string;
+}
+export interface BookendInfo {
+    organization?: string;
+    presenter?: string;
+    role?: string;
+    date?: string;
+    contact?: string;
+    logoAssetId?: string;
+}
 export interface ContentPage {
+    /** Optional decorative Unicode emoji chosen explicitly by the author/model. */
+    emoji?: string;
     id: string;
     title: string;
-    purpose: 'cover' | 'explain' | 'instruct' | 'compare' | 'evidence' | 'conclude';
+    titleEmphasis?: string[];
+    purpose: "cover" | "explain" | "instruct" | "compare" | "evidence" | "conclude";
     evidence: Evidence[];
     blocks: ContentBlock[];
+    publication?: PublicationInfo;
+    bookend?: BookendInfo;
     caption?: string;
     notes?: string;
     scene?: string;
 }
 export interface ContentPlan {
     version: 1;
-    kind: 'presentation' | 'social';
+    kind: "presentation" | "social";
     title: string;
     pages: ContentPage[];
 }
@@ -95,7 +130,7 @@ export declare class ContentContractError extends Error {
 /** Lossless ranges. File-name placeholders are references, never fabricated assets. */
 export declare function parseSource(input: string): SourceDocument;
 /** Validate untrusted AI output; strip unknown properties and never trust generated code or asset URLs. */
-export declare function validateContentPlan(raw: unknown, source: SourceDocument, expectedKind?: ContentPlan['kind']): ContentPlan;
+export declare function validateContentPlan(raw: unknown, source: SourceDocument, expectedKind?: ContentPlan["kind"]): ContentPlan;
 export declare function contentBlockText(block: ContentBlock): string[];
 /** Validate persisted/editor-authored content without reasserting that user edits came from AI evidence. */
 export declare function validateEditableContentPage(raw: unknown, { allowIncomplete }?: {