@neatico/visual-core 0.0.0-stage → 0.14.0

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,138 @@
-# Temporary Holding Version
+# @neatico/visual-core
 
-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.
+Framework-independent building blocks for editable visual products, extracted from [Neatico](https://www.neatico.com/?utm_source=github&utm_medium=readme&utm_campaign=visual-core).
+
+Create visuals with AI at **[neatico.com](https://www.neatico.com/?utm_source=npm&utm_medium=readme&utm_campaign=visual-core)**, or use this package to build your own editor, layout pipeline, or scene extension.
+
+## Install
+
+```sh
+npm install @neatico/visual-core
+```
+
+This package provides native ES modules and TypeScript declarations. It uses the MIT-licensed `linebreak` package for Unicode line opportunities and does not require React, a browser, a database, or an AI provider. Node.js 20 or later is supported. CommonJS projects can use `require()` or dynamic `import()`.
+
+## 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 angles are in degrees. Transforms use the center of the element as their origin. `flattenGroupLayout` preserves additional child properties and returns a new object. It supports translation, rotation, scaling, skew, and horizontal or vertical flips. Nonfinite values, negative dimensions, and degenerate ungrouping transforms fail explicitly.
+
+Additional exports include `layoutMatrix`, `multiplyMatrix`, `layoutBounds`, and the `Layout` and `Matrix` types. Matrices use the six-value CSS affine format `[a, b, c, d, e, f]`.
+
+## Wrap text using your font measurements
+
+```ts
+import { wrapCopy } from "@neatico/visual-core";
+
+const context = 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) => {
+    context.font = `${bold ? 700 : 400} ${size}px Inter`;
+    return context.measureText(text).width;
+  },
+);
+```
+
+Supply measurements for the actual font used by your renderer. Explicit line breaks are preserved. Break opportunities follow UAX #14 through [linebreak](https://github.com/foliojs/linebreak) (Unicode 13); oversized tokens use grapheme boundaries where `Intl.Segmenter` is available. A grapheme wider than the available line fails explicitly. Tiny trailing lines are balanced without adding lines; pass `{ balance: false }` as the sixth argument to disable this. Titles may opt into `{ keepWords: true, preferClauseBreaks: true }` to respect available word segmentation and a fitting topic prefix before a colon. Dictionary segmentation is language-dependent and is not a semantic guarantee. Hyphenation, font shaping and cross-device font installation remain the renderer’s responsibility. Returned lines are plain text; escape them before inserting them 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();
+```
+
+Registries are isolated instances. Duplicate names and unknown scenes throw errors. Renderers own their input validation and output format, so you can return your own canvas schema, SVG tree, or other representation. Async renderers are supported by choosing a promise as the output type. No global registry is created.
+
+## Development
+
+```sh
+npm ci
+npm test
+npm pack --dry-run
+```
+
+Tests cover transform equivalence, invalid geometry, text wrapping, and extension isolation. `npm pack` runs the build and tests before assembling the package. Only compiled output, this README, and the license are published.
+
+## Contributing
+
+Open an issue or pull request at [neatico/visual-core](https://github.com/neatico/visual-core). Include 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).
+
+## Portable template blueprints
+
+`validateBlueprint` accepts a versioned, data-only template with an `id`, localized
+`labels` (including `en` as the fallback), required `fields`, supported `ratios`,
+and a `composition`. Every required field must be bound exactly once. The
+composition validator returns only supported structural properties; executable
+markup and arbitrary style properties are not part of this contract.
+
+```ts
+import { createBlueprintRegistry, blueprintLabel } from '@neatico/visual-core';
+
+const catalog = createBlueprintRegistry();
+const unregister = catalog.register({
+  version: 1,
+  id: 'editorial-introduction',
+  labels: { en: 'Editorial introduction', zh: '编辑式导言' },
+  fields: ['title', 'body'],
+  ratios: [1, 16 / 9],
+  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);
+const name = blueprintLabel(choices[0], 'zh-CN');
+unregister();
+```
+
+Registries are isolated, reject duplicate IDs, and return defensive copies.
+Field matching is exact: a template cannot silently omit extra user content.
+Locale lookup tries the exact locale, then its language, then English.
+
+Structural validation is not visual approval. Before registering AI-authored
+blueprints in a production catalog, the host must render representative samples
+at every supported ratio with the actual font metrics and check bounds, text
+collisions, readability, and content preservation. The host also owns persistence,
+workspace permissions, review status, and migration between blueprint versions.
+
+## Content-aware layout eligibility (0.6)
+
+`LAYOUT_CONTRACTS` covers all 97 slide and 97 social IDs with semantic intent,
+item capacity, required fields and ratio bounds. `eligibleLayouts` filters the
+catalog, and `layoutCandidates` returns a bounded deterministic shortlist.
+These are structural eligibility checks, not a guarantee that arbitrary copy
+fits. Hosts must measure emitted geometry, verify all source fields remain
+visible and reject or paginate unreadable output. No text is rewritten here.
+
+Blueprints may declare `intents` (0.8.0), such as `['cover']` for presentation layouts or `['features']` for social scenes. Registry lookup accepts the semantic intent as its third argument and excludes scoped templates when the intent is absent or incompatible. Omit this property only for deliberately generic layouts. This keeps identical field shapes from turning a cover-only layout into a closing slide or unrelated social format.

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;
+}