@fungi.computer/sprite-zdog 0.0.0-stage → 0.0.1

package/dist/author.js

@@ -0,0 +1,372 @@
+import { COLOR_PREFIX, asInternalNode, getDefinitionInternals, registerInternalNode, setDefinitionInternals, } from "./internal.js";
+const sceneNodeBrand = Symbol("Sprite.SceneNode");
+const finite = (value, label) => {
+    if (!Number.isFinite(value))
+        throw new Error(`Sprite ${label} must be finite`);
+};
+const validateTransform = (value, label) => {
+    if (!value)
+        return;
+    for (const axis of ["x", "y", "z"]) {
+        const coordinate = value[axis];
+        if (coordinate !== undefined)
+            finite(coordinate, `${label}.${axis}`);
+    }
+};
+const validateMotion = (motion, label) => {
+    if (!motion.target.trim())
+        throw new Error(`Sprite ${label}.target cannot be empty`);
+    validateTransform(motion.translate, `${label}.translate`);
+    validateTransform(motion.rotate, `${label}.rotate`);
+    if (motion.durationMs !== undefined) {
+        finite(motion.durationMs, `${label}.durationMs`);
+        if (motion.durationMs < 0)
+            throw new Error(`Sprite ${label}.durationMs cannot be negative`);
+    }
+};
+function isSnapshotArray(value) {
+    return Array.isArray(value);
+}
+function cloneAndFreeze(value, seen = new WeakMap()) {
+    if (value === null ||
+        !(value instanceof Object) ||
+        value instanceof Function) {
+        return value;
+    }
+    const key = value;
+    const prior = seen.get(key);
+    if (prior !== undefined)
+        return prior;
+    if (isSnapshotArray(value)) {
+        const copy = value.map((entry) => cloneAndFreeze(entry, seen));
+        seen.set(key, copy);
+        return Object.freeze(copy);
+    }
+    const copy = {};
+    seen.set(key, copy);
+    for (const [property, entry] of Object.entries(value)) {
+        copy[property] = cloneAndFreeze(entry, seen);
+    }
+    return Object.freeze(copy);
+}
+const freezeValue = (value, seen = new Set()) => {
+    if (value === null ||
+        value === undefined ||
+        !isSnapshotObject(value) ||
+        seen.has(value))
+        return;
+    const key = value;
+    seen.add(key);
+    const entries = Object.values(value);
+    for (const entry of entries) {
+        freezeValue(entry, seen);
+    }
+    Object.freeze(value);
+};
+const isSnapshotObject = (value) => Object(value) === value && !(value instanceof Function);
+const freezeScene = (root) => {
+    const visited = new Set();
+    const visit = (node) => {
+        if (visited.has(node))
+            return;
+        visited.add(node);
+        for (const child of node.children)
+            visit(child);
+        freezeValue(node.options);
+        Object.freeze(node.children);
+        Object.freeze(node);
+    };
+    visit(root);
+};
+const validatePath = (path, label) => {
+    for (const [index, step] of path.entries()) {
+        if ("bezier" in step) {
+            for (const [controlIndex, point] of step.bezier.entries()) {
+                finite(point.x, `${label}[${String(index)}].bezier[${String(controlIndex)}].x`);
+                finite(point.y, `${label}[${String(index)}].bezier[${String(controlIndex)}].y`);
+                if (point.z !== undefined)
+                    finite(point.z, `${label}[${String(index)}].bezier[${String(controlIndex)}].z`);
+            }
+        }
+        else {
+            finite(step.x, `${label}[${String(index)}].x`);
+            finite(step.y, `${label}[${String(index)}].y`);
+            if (step.z !== undefined)
+                finite(step.z, `${label}[${String(index)}].z`);
+        }
+    }
+};
+const valueForBlush = (value) => {
+    if (!value)
+        return "off";
+    if (value <= 0.5)
+        return "small";
+    if (value <= 0.8)
+        return "medium";
+    return "big";
+};
+const validateVariant = (variants, channel, variant) => {
+    const channelVariants = variants.get(channel);
+    if (!channelVariants)
+        throw new Error(`Unknown Sprite variant channel: ${channel}`);
+    if (!channelVariants.has(variant))
+        throw new Error(`Unknown Sprite variant: ${channel}.${variant}`);
+};
+const validateGeometry = (geometry, label, expressions, variants) => {
+    if (!geometry)
+        return;
+    if (geometry.expression !== undefined &&
+        !(geometry.expression in expressions)) {
+        throw new Error(`Unknown Sprite ${label}.expression: ${geometry.expression}`);
+    }
+    if (geometry.eyes !== undefined)
+        validateVariant(variants, "eyes", geometry.eyes);
+    if (geometry.mouth !== undefined)
+        validateVariant(variants, "mouth", geometry.mouth);
+    if (geometry.blush !== undefined) {
+        finite(geometry.blush, `${label}.blush`);
+        validateVariant(variants, "blush", valueForBlush(geometry.blush));
+    }
+};
+/** The standard presentation activities every Sprite understands. */
+export const STANDARD_ACTIVITIES = [
+    "idle",
+    "listening",
+    "processing",
+    "speaking",
+    "thinking",
+    "error",
+];
+const standardActivityNames = new Set(STANDARD_ACTIVITIES);
+const createScene = () => {
+    const owner = Symbol("sprite-scene");
+    const nodes = new Map();
+    const variants = new Map();
+    const makeNode = (kind, options = {}) => {
+        const name = options.name;
+        if (options.name !== undefined && (!name || name.trim() === "")) {
+            throw new Error("Sprite node name cannot be empty");
+        }
+        if (name && nodes.has(name))
+            throw new Error(`Duplicate Sprite node name: ${name}`);
+        const { parent: parentOption, ...nodeOptions } = options;
+        const parent = parentOption ? asInternalNode(parentOption) : undefined;
+        if (parent && parent.owner !== owner)
+            throw new Error("Sprite nodes cannot cross scene definitions");
+        validateTransform(options.translate, "translate");
+        validateTransform(options.rotate, "rotate");
+        validateTransform(options.scale, "scale");
+        if (options.stroke !== undefined && options.stroke !== false)
+            finite(options.stroke, "stroke");
+        const node = {
+            owner,
+            kind,
+            name,
+            parent,
+            children: [],
+            options: {
+                ...nodeOptions,
+                translate: options.x !== undefined ||
+                    options.y !== undefined ||
+                    options.z !== undefined
+                    ? {
+                        ...options.translate,
+                        x: options.x ?? options.translate?.x,
+                        y: options.y ?? options.translate?.y,
+                        z: options.z ?? options.translate?.z,
+                    }
+                    : options.translate,
+            },
+        };
+        if (parent)
+            parent.children.push(node);
+        if (name)
+            nodes.set(name, node);
+        const publicNode = { [sceneNodeBrand]: true };
+        registerInternalNode(publicNode, node);
+        return publicNode;
+    };
+    const scene = {
+        group: (options = {}) => makeNode("group", options),
+        path: (options) => {
+            if (options.path)
+                validatePath(options.path, "shape.path");
+            return makeNode("shape", options);
+        },
+        ellipse: (options) => {
+            finite(options.width, "ellipse.width");
+            finite(options.height, "ellipse.height");
+            return makeNode("ellipse", options);
+        },
+        hemisphere: (options) => {
+            finite(options.diameter, "hemisphere.diameter");
+            return makeNode("hemisphere", options);
+        },
+        cylinder: (options) => {
+            finite(options.diameter, "cylinder.diameter");
+            finite(options.length, "cylinder.length");
+            return makeNode("cylinder", options);
+        },
+    };
+    return { scene, owner, nodes, variants };
+};
+/** Validate and freeze one renderer-neutral Sprite definition. */
+export function defineSprite(input) {
+    if (!Object.is(input.apiVersion, 1))
+        throw new Error("Sprite definitions must declare apiVersion: 1");
+    if (!input.name.trim())
+        throw new Error("Sprite definition name cannot be empty");
+    if (!Object.keys(input.palette).length)
+        throw new Error("Sprite definitions need a palette");
+    for (const [name, value] of Object.entries(input.palette)) {
+        if (!name.trim() || !value.trim())
+            throw new Error(`Invalid Sprite palette entry: ${name}`);
+    }
+    if (!Object.keys(input.expressions).length)
+        throw new Error("Sprite definitions need an expression");
+    const snapshot = cloneAndFreeze({
+        ...input,
+        palette: input.palette,
+        expressions: input.expressions,
+        activities: input.activities ?? {},
+    });
+    const built = createScene();
+    const color = (name) => {
+        if (!(name in snapshot.palette))
+            throw new Error(`Unknown Sprite palette slot: ${name}`);
+        return `${COLOR_PREFIX}${name}`;
+    };
+    const result = snapshot.build({ scene: built.scene, color });
+    if (Object.is(result, null) ||
+        Object.is(result, undefined) ||
+        !Object.hasOwn(result, "root") ||
+        Object.is(result.root, null) ||
+        Object.is(result.root, undefined))
+        throw new Error("Sprite build must return a root node");
+    const root = asInternalNode(result.root);
+    if (root.owner !== built.owner)
+        throw new Error("Sprite root belongs to another definition");
+    for (const [channel, values] of Object.entries(result.variants ?? {})) {
+        const channelVariants = new Map();
+        for (const [variant, node] of Object.entries(values)) {
+            const internal = asInternalNode(node);
+            if (internal.owner !== built.owner)
+                throw new Error(`Sprite variant is from another definition: ${channel}.${variant}`);
+            channelVariants.set(variant, internal);
+        }
+        built.variants.set(channel, channelVariants);
+    }
+    for (const [expressionName, expression] of Object.entries(snapshot.expressions)) {
+        for (const [channel, variant] of Object.entries(expression.variants ?? {})) {
+            const channelVariants = built.variants.get(channel);
+            if (!channelVariants)
+                throw new Error(`Unknown Sprite variant channel: ${channel}`);
+            if (!channelVariants.has(variant)) {
+                throw new Error(`Unknown Sprite variant: ${channel}.${variant}`);
+            }
+        }
+        for (const [channel, choices] of Object.entries(expression.variantChoices ?? {})) {
+            const channelVariants = built.variants.get(channel);
+            if (!channelVariants)
+                throw new Error(`Unknown Sprite variant channel: ${channel}`);
+            if (!choices.length)
+                throw new Error(`Sprite expression choices cannot be empty: ${expressionName}.${channel}`);
+            for (const variant of choices) {
+                if (!channelVariants.has(variant))
+                    throw new Error(`Unknown Sprite variant: ${channel}.${variant}`);
+            }
+        }
+        if (!expressionName.trim())
+            throw new Error("Sprite expression name cannot be empty");
+    }
+    const activities = snapshot.activities;
+    for (const [activityName, activity] of Object.entries(activities)) {
+        if (!activityName.trim())
+            throw new Error("Sprite activity name cannot be empty");
+        if (activity.motion) {
+            validateMotion(activity.motion, `activity.${activityName}.motion`);
+            if (!built.nodes.has(activity.motion.target)) {
+                throw new Error(`Unknown Sprite activity target: ${activity.motion.target}`);
+            }
+        }
+        if (activity.mouseInfluence !== undefined)
+            finite(activity.mouseInfluence, `activity.${activityName}.mouseInfluence`);
+        validateGeometry(activity.geometry, `activity.${activityName}.geometry`, snapshot.expressions, built.variants);
+        for (const [index, step] of (activity.mouthCycle ?? []).entries()) {
+            finite(step.durationMs, `activity.${activityName}.mouthCycle[${String(index)}].durationMs`);
+            if (step.durationMs < 0)
+                throw new Error(`Sprite activity.${activityName}.mouthCycle[${String(index)}].durationMs cannot be negative`);
+        }
+    }
+    for (const [expressionName, expression] of Object.entries(snapshot.expressions)) {
+        if (expression.blush !== undefined) {
+            finite(expression.blush, `expression.${expressionName}.blush`);
+            validateVariant(built.variants, "blush", valueForBlush(expression.blush));
+        }
+        if (expression.motion) {
+            validateMotion(expression.motion, `expression.${expressionName}.motion`);
+            if (!built.nodes.has(expression.motion.target))
+                throw new Error(`Unknown Sprite expression target: ${expression.motion.target}`);
+        }
+    }
+    const firstExpression = Object.keys(snapshot.expressions)[0];
+    const defaultExpression = snapshot.defaultPresentation?.expression ?? firstExpression;
+    if (!defaultExpression || !(defaultExpression in snapshot.expressions)) {
+        throw new Error(`Unknown Sprite default expression: ${String(defaultExpression)}`);
+    }
+    const defaultActivity = snapshot.defaultPresentation?.activity ?? "idle";
+    if (snapshot.defaultPresentation?.activity !== undefined &&
+        !STANDARD_ACTIVITIES.some((activity) => activity === defaultActivity) &&
+        !(defaultActivity in activities)) {
+        throw new Error(`Unknown Sprite default activity: ${defaultActivity}`);
+    }
+    for (const node of built.nodes.values())
+        freezeScene(node);
+    const definition = snapshot;
+    const variantNodes = new Set();
+    for (const channel of built.variants.values()) {
+        for (const node of channel.values())
+            variantNodes.add(node);
+    }
+    setDefinitionInternals(definition, {
+        owner: built.owner,
+        root,
+        nodesByName: built.nodes,
+        variants: built.variants,
+        variantNodes,
+        palette: snapshot.palette,
+        activities,
+        expressions: snapshot.expressions,
+        defaultActivity,
+        defaultExpression,
+    });
+    return definition;
+}
+/** Return a compact, machine-readable receipt for an already authored definition. */
+export const check = (definition) => {
+    const internals = getDefinitionInternals(definition);
+    const visited = new Set();
+    const visit = (node) => {
+        if (visited.has(node))
+            return;
+        visited.add(node);
+        for (const child of node.children)
+            visit(child);
+    };
+    visit(internals.root);
+    const variants = {};
+    for (const [channel, values] of internals.variants)
+        variants[channel] = [...values.keys()];
+    return {
+        valid: true,
+        name: definition.name,
+        nodeCount: visited.size,
+        expressions: Object.keys(internals.expressions),
+        activities: [
+            ...STANDARD_ACTIVITIES,
+            ...Object.keys(internals.activities).filter((name) => !standardActivityNames.has(name)),
+        ],
+        variants,
+    };
+};
+export { toCharacter } from "./portable.js";

package/dist/avatar.d.ts

@@ -0,0 +1,69 @@
+import * as z from "zod";
+import type { AgentColors, Avatar } from "@fungi.computer/sprite/avatar";
+export { avatarCatalog } from "./catalog.js";
+/**
+ * The Avatar v1 schema, refined against every built-in character's facts:
+ * the one callers should actually parse untrusted data with. (The unrefined
+ * envelope lives at `@fungi.computer/sprite/avatar`'s `avatarEnvelopeSchema`,
+ * for a caller building a different catalog.)
+ */
+export declare const avatarSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    character: z.ZodEnum<{
+        mushroom: "mushroom";
+        cat: "cat";
+        burger: "burger";
+    }>;
+    appearance: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    expression: z.ZodString;
+    renderStyle: z.ZodEnum<{
+        plain: "plain";
+        pencil: "pencil";
+        manga: "manga";
+        riso: "riso";
+        halftone: "halftone";
+        blueprint: "blueprint";
+        crt: "crt";
+        watercolor: "watercolor";
+    }>;
+}, z.core.$strict>;
+/** Parse an unknown value into a built-in-character-valid Avatar v1 descriptor. */
+export declare function parseAvatar(data: unknown): Avatar;
+/**
+ * Derive an Agent's avatar from its creator's: `deriveAgentAvatar` bound to
+ * the built-in character catalog, so the Hub, Grove's create preview, the
+ * TUI and local Agents all compute the same result without each wiring the
+ * catalog through themselves.
+ */
+export declare function deriveAgentAvatar(member: Avatar, agentColors: AgentColors, seed: string, avoid?: readonly number[]): Avatar;
+/** A person's saved look and preference for the colours of new Agents. */
+export declare const memberAvatarSchema: z.ZodObject<{
+    avatar: z.ZodObject<{
+        v: z.ZodLiteral<1>;
+        character: z.ZodEnum<{
+            mushroom: "mushroom";
+            cat: "cat";
+            burger: "burger";
+        }>;
+        appearance: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+        expression: z.ZodString;
+        renderStyle: z.ZodEnum<{
+            plain: "plain";
+            pencil: "pencil";
+            manga: "manga";
+            riso: "riso";
+            halftone: "halftone";
+            blueprint: "blueprint";
+            crt: "crt";
+            watercolor: "watercolor";
+        }>;
+    }, z.core.$strict>;
+    agentColors: z.ZodEnum<{
+        shift: "shift";
+        keep: "keep";
+    }>;
+}, z.core.$strict>;
+/** Catalog-validated account avatar preference. */
+export type MemberAvatar = z.infer<typeof memberAvatarSchema>;
+/** The uncustomized mascot and default colour-shift preference. */
+export declare const defaultMemberAvatar: MemberAvatar;

package/dist/avatar.js

@@ -0,0 +1,40 @@
+import * as z from "zod";
+import { agentColorsSchema, createAvatarSchema, deriveAgentAvatar as deriveAgentAvatarWithCatalog, } from "@fungi.computer/sprite/avatar";
+import { avatarCatalog } from "./catalog.js";
+export { avatarCatalog } from "./catalog.js";
+/**
+ * The Avatar v1 schema, refined against every built-in character's facts:
+ * the one callers should actually parse untrusted data with. (The unrefined
+ * envelope lives at `@fungi.computer/sprite/avatar`'s `avatarEnvelopeSchema`,
+ * for a caller building a different catalog.)
+ */
+export const avatarSchema = createAvatarSchema(avatarCatalog);
+/** Parse an unknown value into a built-in-character-valid Avatar v1 descriptor. */
+export function parseAvatar(data) {
+    return avatarSchema.parse(data);
+}
+/**
+ * Derive an Agent's avatar from its creator's: `deriveAgentAvatar` bound to
+ * the built-in character catalog, so the Hub, Grove's create preview, the
+ * TUI and local Agents all compute the same result without each wiring the
+ * catalog through themselves.
+ */
+export function deriveAgentAvatar(member, agentColors, seed, avoid = []) {
+    return deriveAgentAvatarWithCatalog(member, agentColors, seed, avatarCatalog, avoid);
+}
+/** A person's saved look and preference for the colours of new Agents. */
+export const memberAvatarSchema = z.strictObject({
+    avatar: avatarSchema,
+    agentColors: agentColorsSchema,
+});
+/** The uncustomized mascot and default colour-shift preference. */
+export const defaultMemberAvatar = {
+    avatar: {
+        v: 1,
+        character: "mushroom",
+        appearance: {},
+        expression: "normal",
+        renderStyle: "plain",
+    },
+    agentColors: "shift",
+};