@ludic-labs/assembly 0.0.0-stage → 0.4.0

package/dist/sprite-types.d.ts

@@ -0,0 +1,110 @@
+/** Loose JSON input. The compiler validates structure and semantics at runtime. */
+export type SpriteDocument = Record<string, unknown>;
+export type SpritePoint = [number, number];
+export type SpriteBox = [number, number, number, number];
+export type SpriteColour = [number, number, number, number];
+export interface SpriteDiagnostic {
+    severity: "error" | "warning";
+    code: string;
+    path: string;
+    message: string;
+    part?: string;
+    received?: unknown;
+    expected?: unknown;
+}
+export interface SpriteGuidePart {
+    bbox: SpriteBox;
+    area: number;
+    mask: number[];
+    instance?: boolean;
+    depth?: number;
+    z?: number;
+    projected?: SpriteBox;
+    subpixel?: boolean;
+}
+export interface SpriteGuide {
+    width: number;
+    height: number;
+    parts: Record<string, SpriteGuidePart>;
+    hidden?: string[];
+    owners?: Int32Array;
+    depth?: Float32Array | Float64Array;
+    /** Per pixel, the light tone of the visible surface (/pixel roles: 0 outline, 1 deep, 2 shadow, 3 mid, 4 light; -1 empty). */
+    roles?: Int8Array;
+    instances?: string[];
+    originX?: number;
+    originY?: number;
+    cut?: string[];
+    pixelsPerMetre?: number;
+    camera?: string;
+}
+export interface SpriteView {
+    camera: string | {
+        yaw: number;
+        pitch: number;
+    };
+    pixelsPerMetre: number;
+    margin?: number;
+    hide?: string[];
+    pose?: {
+        clip: string;
+        phase: number;
+    };
+    notes?: unknown;
+}
+export interface SpriteRenderSpec {
+    camera?: SpriteView["camera"];
+    pixelsPerMetre?: number;
+    /** Exact occupied row count, taking precedence over pixelsPerMetre. */
+    fitHeight?: number;
+    margin?: number;
+    profile?: string;
+    features?: string[];
+    snap?: boolean;
+}
+export interface SpriteRenderBase {
+    width: number;
+    height: number;
+    rgba: Uint8Array;
+    owners: Int32Array;
+    names: string[];
+}
+export interface CompileSpriteOptions {
+    renderBase?: (spec: SpriteRenderSpec, path: string) => SpriteRenderBase;
+    guide?: (view: SpriteView, path: string) => SpriteGuide;
+}
+export interface SpriteCel {
+    id: string;
+    canvas: import("./sprite-compiler.js").SpriteCanvas;
+    pivot: SpritePoint;
+    view: string | null;
+}
+export interface SpriteAnchor {
+    path: string;
+    part?: string;
+    guide?: string;
+    point: SpritePoint;
+}
+export interface SpriteGuideReport {
+    cel: string;
+    part: string;
+    guide: SpriteBox;
+    authored: SpriteBox | null;
+    overlap: number;
+    guideArea: number;
+    area: number;
+}
+export interface SpriteResult {
+    ok: boolean;
+    diagnostics: SpriteDiagnostic[];
+    parts: string[];
+    cels: Map<string, SpriteCel>;
+    animations: Map<string, {
+        cels: string[];
+        ms: number[];
+        loop: boolean;
+    }>;
+    anchors: SpriteAnchor[];
+    guides: Map<string, SpriteGuide | null>;
+    guideReport: SpriteGuideReport[];
+}

package/dist/sprite-types.js

@@ -0,0 +1 @@
+export {};

package/dist/sprite.d.ts

@@ -0,0 +1,8 @@
+/** Typed, host-independent pixel sprites and guided scene composition. */
+export * from "./sprite-types.js";
+export * from "./sprite-compiler.js";
+export * from "./sprite-guide.js";
+export * from "./sprite-decompile.js";
+export * from "./sprite-scene.js";
+export * from "./sprite-format.js";
+export * from "./sprite-brief.js";

package/dist/sprite.js

@@ -0,0 +1,8 @@
+/** Typed, host-independent pixel sprites and guided scene composition. */
+export * from "./sprite-types.js";
+export * from "./sprite-compiler.js";
+export * from "./sprite-guide.js";
+export * from "./sprite-decompile.js";
+export * from "./sprite-scene.js";
+export * from "./sprite-format.js";
+export * from "./sprite-brief.js";

package/dist/svg/schema.d.ts

@@ -0,0 +1,71 @@
+/** One structural definition feeds the dependency-free checker and published JSON Schema. */
+export interface Rule {
+    $ref?: string;
+    type?: string;
+    const?: unknown;
+    enum?: unknown[];
+    oneOf?: Rule[];
+    properties?: Record<string, Rule>;
+    required?: string[];
+    additionalProperties?: boolean | Rule;
+    propertyNames?: Rule;
+    items?: Rule | false;
+    prefixItems?: Rule[];
+    minItems?: number;
+    maxItems?: number;
+    maxProperties?: number;
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+}
+export declare const svgAssetSchema: {
+    $ref?: string;
+    type?: string;
+    const?: unknown;
+    enum?: unknown[];
+    oneOf?: Rule[];
+    properties?: Record<string, Rule>;
+    required?: string[];
+    additionalProperties?: boolean | Rule;
+    propertyNames?: Rule;
+    items?: Rule | false;
+    prefixItems?: Rule[];
+    minItems?: number;
+    maxItems?: number;
+    maxProperties?: number;
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    $schema: string;
+    $id: string;
+    title: string;
+    description: string;
+    $defs: {
+        expr: {
+            oneOf: Rule[];
+        };
+        paint: {
+            oneOf: Rule[];
+        };
+        command: {
+            oneOf: Rule[];
+        };
+        shape: {
+            oneOf: Rule[];
+        };
+        node: {
+            oneOf: Rule[];
+        };
+        gradient: {
+            oneOf: Rule[];
+        };
+    };
+};
+/** Only the closed subset used above; this is not a general JSON Schema interpreter. */
+export declare function checkStructure(value: unknown, rule?: Rule, path?: string, depth?: number): string | null;

package/dist/svg/schema.js

@@ -0,0 +1,217 @@
+const ref = (name) => ({ $ref: `#/$defs/${name}` });
+const num = (minimum = -1e6, maximum = 1e6) => ({ type: "number", minimum, maximum });
+const text = (maxLength = 120) => ({ type: "string", maxLength, minLength: 1 });
+const id = { ...text(64), pattern: "^[A-Za-z][A-Za-z0-9_-]*$" };
+const color = { type: "string", pattern: "^#[0-9a-fA-F]{6}$" };
+const arr = (items, minItems = 0, maxItems = 512) => ({
+    type: "array",
+    items,
+    minItems,
+    maxItems,
+});
+const tuple = (...prefixItems) => ({
+    type: "array",
+    prefixItems,
+    items: false,
+    minItems: prefixItems.length,
+    maxItems: prefixItems.length,
+});
+const obj = (properties, required = Object.keys(properties)) => ({
+    type: "object",
+    properties,
+    required,
+    additionalProperties: false,
+});
+const dict = (value) => ({
+    type: "object",
+    propertyNames: id,
+    additionalProperties: value,
+    maxProperties: 128,
+});
+const expr = ref("expr"), point = tuple(expr, expr);
+const base = {
+    id,
+    transform: obj({ translate: point, rotate: expr, scale: point, pivot: point }, []),
+    style: obj({
+        fill: ref("paint"),
+        stroke: ref("paint"),
+        strokeWidth: expr,
+        linecap: { enum: ["butt", "round", "square"] },
+        linejoin: { enum: ["miter", "round", "bevel"] },
+        fillRule: { enum: ["nonzero", "evenodd"] },
+    }, []),
+    opacity: expr,
+    clip: id,
+    mask: id,
+    blur: expr,
+};
+const node = (kind, fields, required = Object.keys(fields)) => obj({ ...base, kind: { const: kind }, ...fields }, ["id", "kind", ...required]);
+const shapes = [
+    node("rect", { x: expr, y: expr, width: expr, height: expr, radius: expr }, ["x", "y", "width", "height"]),
+    node("ellipse", { cx: expr, cy: expr, rx: expr, ry: expr }),
+    node("path", { d: arr(ref("command"), 1, 2048) }),
+];
+const count = { type: "integer", minimum: 1, maximum: 1024 };
+const param = obj({ default: num(), min: num(), max: num() });
+const stop = obj({ offset: num(0, 1), color, opacity: num(0, 1) }, ["offset", "color"]);
+export const svgAssetSchema = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: "https://libraries.ludic-assembly.victorqueiroz.dev/schema/svg-asset-0.1.json",
+    title: "SVG Asset Notation 0.1",
+    description: "Structural validation. compileSvgAsset additionally validates references, scopes, cycles, key ordering and evaluated geometry.",
+    ...obj({
+        schema: { const: "svg-asset/0.1" },
+        name: text(),
+        viewBox: tuple(num(), num(), { ...num(0), exclusiveMinimum: 0 }, { ...num(0), exclusiveMinimum: 0 }),
+        seed: { type: "integer", minimum: 0, maximum: 4294967295 },
+        params: dict(param),
+        palette: dict(color),
+        gradients: dict(ref("gradient")),
+        clips: dict(arr(ref("shape"), 1)),
+        masks: dict(arr(ref("shape"), 1)),
+        symbols: dict(obj({ params: dict(param), children: arr(ref("node"), 1) }, ["children"])),
+        animations: dict(obj({
+            duration: { ...num(0, 60), exclusiveMinimum: 0 },
+            loop: { type: "boolean" },
+            tracks: dict(arr(obj({ time: num(0, 60), value: num(), ease: { enum: ["linear", "smooth", "hold"] } }, [
+                "time",
+                "value",
+            ]), 2, 256)),
+        })),
+        defaultAnimation: id,
+        nodes: arr(ref("node"), 1),
+    }, ["schema", "name", "viewBox", "nodes"]),
+    $defs: {
+        expr: {
+            oneOf: [
+                num(),
+                { type: "string", pattern: "^\\$[A-Za-z][A-Za-z0-9_-]*$", maxLength: 65 },
+                ...[
+                    ["sin", "cos", "abs"],
+                    ["add", "sub", "mul", "div", "min", "max"],
+                    ["clamp", "mix", "rand"],
+                ].map((ops, index) => tuple({ enum: ops }, ...Array.from({ length: index + 1 }, () => expr))),
+            ],
+        },
+        paint: {
+            oneOf: [
+                color,
+                { const: "none" },
+                { type: "string", pattern: "^@[A-Za-z][A-Za-z0-9_-]*$", maxLength: 65 },
+                obj({ gradient: id }),
+            ],
+        },
+        command: {
+            oneOf: [
+                tuple({ enum: ["M", "L"] }, expr, expr),
+                tuple({ const: "Q" }, expr, expr, expr, expr),
+                tuple({ const: "C" }, expr, expr, expr, expr, expr, expr),
+                tuple({ const: "A" }, expr, expr, expr, { enum: [0, 1] }, { enum: [0, 1] }, expr, expr),
+                tuple({ const: "Z" }),
+            ],
+        },
+        shape: { oneOf: shapes },
+        node: {
+            oneOf: [
+                ...shapes,
+                node("group", { children: arr(ref("node"), 1) }),
+                node("use", { symbol: id, args: dict(expr) }, ["symbol"]),
+                node("repeat", { count, children: arr(ref("node"), 1) }),
+                node("emitter", {
+                    count,
+                    lifetime: { ...num(0, 60), exclusiveMinimum: 0 },
+                    mode: { enum: ["loop", "burst"] },
+                    start: num(0, 60),
+                    velocity: point,
+                    acceleration: point,
+                    children: arr(ref("node"), 1),
+                }, ["count", "lifetime", "mode", "velocity", "children"]),
+            ],
+        },
+        gradient: {
+            oneOf: [
+                obj({ kind: { const: "linear" }, from: point, to: point, stops: arr(stop, 2, 32) }),
+                obj({ kind: { const: "radial" }, center: point, radius: expr, stops: arr(stop, 2, 32) }),
+            ],
+        },
+    },
+};
+/** Only the closed subset used above; this is not a general JSON Schema interpreter. */
+export function checkStructure(value, rule = svgAssetSchema, path = "$", depth = 0) {
+    if (depth > 96)
+        return `${path}: nesting exceeds 96`;
+    if (rule.$ref)
+        return checkStructure(value, svgAssetSchema.$defs[rule.$ref.slice(8)], path, depth + 1);
+    if (rule.oneOf) {
+        const results = rule.oneOf.map((r) => checkStructure(value, r, path, depth + 1));
+        return results.filter((r) => r === null).length === 1 ? null : `${path}: does not match a supported form`;
+    }
+    if ("const" in rule && value !== rule.const)
+        return `${path}: expected ${String(rule.const)}`;
+    if (rule.enum && !rule.enum.includes(value))
+        return `${path}: unsupported value`;
+    if (rule.type === "number" || rule.type === "integer") {
+        if (typeof value !== "number" ||
+            !Number.isFinite(value) ||
+            (rule.type === "integer" && !Number.isInteger(value)))
+            return `${path}: expected finite ${rule.type}`;
+        if ((rule.minimum !== undefined && value < rule.minimum) ||
+            (rule.maximum !== undefined && value > rule.maximum) ||
+            (rule.exclusiveMinimum !== undefined && value <= rule.exclusiveMinimum))
+            return `${path}: number outside supported bounds`;
+    }
+    if (rule.type === "string") {
+        if (typeof value !== "string")
+            return `${path}: expected string`;
+        if ((rule.minLength && value.length < rule.minLength) ||
+            (rule.maxLength && value.length > rule.maxLength) ||
+            (rule.pattern && !new RegExp(rule.pattern).test(value)))
+            return `${path}: invalid string`;
+    }
+    if (rule.type === "boolean" && typeof value !== "boolean")
+        return `${path}: expected boolean`;
+    if (rule.type === "array") {
+        if (!Array.isArray(value))
+            return `${path}: expected array`;
+        if (value.length < (rule.minItems ?? 0) || value.length > (rule.maxItems ?? Infinity))
+            return `${path}: invalid array length`;
+        for (let i = 0; i < value.length; i++) {
+            const item = rule.prefixItems?.[i] ?? rule.items;
+            if (item === false)
+                return `${path}[${i}]: extra item`;
+            if (item) {
+                const error = checkStructure(value[i], item, `${path}[${i}]`, depth + 1);
+                if (error)
+                    return error;
+            }
+        }
+    }
+    if (rule.type === "object") {
+        if (value === null || typeof value !== "object" || Array.isArray(value))
+            return `${path}: expected object`;
+        const record = value, keys = Object.keys(record);
+        if (keys.length > (rule.maxProperties ?? Infinity))
+            return `${path}: too many entries`;
+        for (const key of rule.required ?? [])
+            if (!Object.hasOwn(record, key))
+                return `${path}.${key}: required`;
+        for (const key of keys) {
+            if (rule.propertyNames) {
+                const error = checkStructure(key, rule.propertyNames, `${path}.${key}`, depth + 1);
+                if (error)
+                    return error;
+            }
+            const child = rule.properties && Object.hasOwn(rule.properties, key)
+                ? rule.properties[key]
+                : rule.additionalProperties;
+            if (child === false)
+                return `${path}.${key}: unknown property`;
+            if (typeof child === "object") {
+                const error = checkStructure(record[key], child, `${path}.${key}`, depth + 1);
+                if (error)
+                    return error;
+            }
+        }
+    }
+    return null;
+}

package/dist/svg/types.d.ts

@@ -0,0 +1,148 @@
+/** SVG Asset Notation 0.1. Coordinates are SVG user units; time is seconds. */
+export type SvgExpr = number | `$${string}` | [SvgOperator, ...SvgExpr[]];
+export type SvgOperator = "add" | "sub" | "mul" | "div" | "min" | "max" | "sin" | "cos" | "abs" | "clamp" | "mix" | "rand";
+export type SvgPoint = [SvgExpr, SvgExpr];
+export type SvgPaint = string | {
+    gradient: string;
+};
+export interface SvgParameter {
+    default: number;
+    min: number;
+    max: number;
+}
+export interface SvgTransform {
+    translate?: SvgPoint;
+    rotate?: SvgExpr;
+    scale?: SvgPoint;
+    pivot?: SvgPoint;
+}
+export interface SvgStyle {
+    fill?: SvgPaint;
+    stroke?: SvgPaint;
+    strokeWidth?: SvgExpr;
+    linecap?: "butt" | "round" | "square";
+    linejoin?: "miter" | "round" | "bevel";
+    fillRule?: "nonzero" | "evenodd";
+}
+export interface SvgNodeBase {
+    id: string;
+    transform?: SvgTransform;
+    style?: SvgStyle;
+    opacity?: SvgExpr;
+    clip?: string;
+    mask?: string;
+    blur?: SvgExpr;
+}
+export type SvgPathCommand = ["M" | "L", SvgExpr, SvgExpr] | ["Q", SvgExpr, SvgExpr, SvgExpr, SvgExpr] | ["C", SvgExpr, SvgExpr, SvgExpr, SvgExpr, SvgExpr, SvgExpr] | ["A", SvgExpr, SvgExpr, SvgExpr, 0 | 1, 0 | 1, SvgExpr, SvgExpr] | ["Z"];
+export type SvgShape = SvgNodeBase & ({
+    kind: "rect";
+    x: SvgExpr;
+    y: SvgExpr;
+    width: SvgExpr;
+    height: SvgExpr;
+    radius?: SvgExpr;
+} | {
+    kind: "ellipse";
+    cx: SvgExpr;
+    cy: SvgExpr;
+    rx: SvgExpr;
+    ry: SvgExpr;
+} | {
+    kind: "path";
+    d: SvgPathCommand[];
+});
+export type SvgNode = SvgShape | (SvgNodeBase & ({
+    kind: "group";
+    children: SvgNode[];
+} | {
+    kind: "use";
+    symbol: string;
+    args?: Record<string, SvgExpr>;
+} | {
+    kind: "repeat";
+    count: number;
+    children: SvgNode[];
+} | {
+    kind: "emitter";
+    count: number;
+    lifetime: number;
+    mode: "loop" | "burst";
+    start?: number;
+    velocity: SvgPoint;
+    acceleration?: SvgPoint;
+    children: SvgNode[];
+}));
+export interface SvgSymbol {
+    params?: Record<string, SvgParameter>;
+    children: SvgNode[];
+}
+export type SvgGradient = {
+    stops: {
+        offset: number;
+        color: string;
+        opacity?: number;
+    }[];
+} & ({
+    kind: "linear";
+    from: SvgPoint;
+    to: SvgPoint;
+} | {
+    kind: "radial";
+    center: SvgPoint;
+    radius: SvgExpr;
+});
+export interface SvgKey {
+    time: number;
+    value: number;
+    ease?: "linear" | "smooth" | "hold";
+}
+export interface SvgClip {
+    duration: number;
+    loop: boolean;
+    tracks: Record<string, SvgKey[]>;
+}
+export interface SvgAssetSpec {
+    schema: "svg-asset/0.1";
+    name: string;
+    viewBox: [number, number, number, number];
+    seed?: number;
+    params?: Record<string, SvgParameter>;
+    palette?: Record<string, string>;
+    gradients?: Record<string, SvgGradient>;
+    clips?: Record<string, SvgShape[]>;
+    masks?: Record<string, SvgShape[]>;
+    symbols?: Record<string, SvgSymbol>;
+    animations?: Record<string, SvgClip>;
+    defaultAnimation?: string;
+    nodes: SvgNode[];
+}
+export interface SvgDiagnostic {
+    code: string;
+    path: string;
+    message: string;
+}
+export interface CompiledSvgAsset {
+    readonly spec: SvgAssetSpec;
+}
+export type SvgCompilation = {
+    ok: true;
+    asset: CompiledSvgAsset;
+    diagnostics: [];
+} | {
+    ok: false;
+    asset: null;
+    diagnostics: SvgDiagnostic[];
+};
+export interface SvgFrameOptions {
+    /** Omit to select defaultAnimation; null renders the rest pose. */
+    animation?: string | null;
+    time?: number;
+    /** Overrides replace sampled animation values, within declared bounds. */
+    params?: Record<string, number>;
+    /** Set a different prefix for each SVG embedded in one HTML document. */
+    prefix?: string;
+}
+export interface SvgAnimationOptions extends Omit<SvgFrameOptions, "time" | "animation"> {
+    animation?: string;
+    fps?: number;
+}

package/dist/svg/types.js

@@ -0,0 +1 @@
+export {};

package/dist/svg.d.ts

@@ -0,0 +1,26 @@
+import type { CompiledSvgAsset, SvgAnimationOptions, SvgCompilation, SvgDiagnostic, SvgFrameOptions } from "./svg/types.js";
+export type * from "./svg/types.js";
+export declare const SVG_ASSET_LIMITS: Readonly<{
+    sourceValues: 100000;
+    sourceCharacters: 2000000;
+    nodesPerFrame: 10000;
+    frames: 240;
+    outputCharacters: 8000000;
+    depth: 32;
+}>;
+export declare class SvgAssetError extends Error {
+    readonly diagnostics: SvgDiagnostic[];
+    constructor(code: string, path: string, message: string);
+}
+/** Validates structure, references and the default/rest frame; never mutates caller input. */
+export declare function compileSvgAsset(input: unknown): SvgCompilation;
+export declare const validateSvgAsset: (input: unknown) => SvgDiagnostic[];
+/** A seek is independent of every previous sample. Loop endpoints wrap; one-shots hold. */
+export declare function sampleSvgParameters(asset: CompiledSvgAsset, options?: SvgFrameOptions): {
+    time: number;
+    phase: number;
+    params: Record<string, number>;
+};
+export declare function renderSvgFrame(asset: CompiledSvgAsset, options?: SvgFrameOptions): string;
+/** Script-free sampled SVG playback. Frame sampling is deliberate, bounded and portable. */
+export declare function exportSvgAnimation(asset: CompiledSvgAsset, options?: SvgAnimationOptions): string;