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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jamstack Consulting LLC
+
+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,126 @@
-# Temporary Holding Version
+# Sprite Zdog (`@fungi.computer/sprite-zdog`)
 
-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.
+Sprite Zdog is an optional Canvas renderer for characters built with Zdog. It
+also provides built-in characters and tools for authoring a portable character
+document that [Sprite](../sprite/README.md) can load.
+
+## Install or set up
+
+```sh
+npm install @fungi.computer/sprite-zdog
+```
+
+The package ships ESM only and depends on Effect, Zod, `animejs`, `zdog`, and
+[Sprite](../sprite/README.md) at runtime. Add it only to a host that already
+uses Sprite and renders with Zdog. The parent Sprite host still owns the player
+and asset policy. The root entrypoint exports the Zdog renderer. `./author` and
+`./portable` support scene authoring. `./builtins` (and the individual
+`./builtins/base`, `./builtins/mushroom`, `./builtins/cat`, and
+`./builtins/burger` subpaths) expose the bundled authoring definitions.
+`./mushroom`, `./cat` and `./burger` provide ready-to-load local characters,
+each with its document and renderer. `./catalog` and `./avatar` provide pure
+avatar validation and derivation without importing the Canvas renderer.
+
+## Quick start
+
+This illustrative example installs the bundled mushroom as a local character and
+renders it with the Sprite React component:
+
+```tsx
+import { createSprite } from "@fungi.computer/sprite";
+import { Sprite } from "@fungi.computer/sprite/react";
+import { builtinCharacters } from "@fungi.computer/sprite-zdog";
+
+const service = createSprite({
+  characters: builtinCharacters,
+});
+
+function Character() {
+  return (
+    <Sprite
+      service={service}
+      src={{ local: "mushroom" }}
+      activity="thinking"
+      role="img"
+      aria-label="Mushroom character"
+    />
+  );
+}
+```
+
+`builtinCharacters` provides lazy `mushroom`, `cat` and `burger` loaders without
+remote asset access. The bundled character supplies its document and Zdog
+renderer together. The tests cover built-in characters and player integration in
+[`src/builtins.test.ts`](src/builtins.test.ts) and
+[`src/mushroom.test.ts`](src/mushroom.test.ts).
+
+## Core concepts
+
+The package root exports the Zdog renderer as the default export. To render a
+served character document whose `renderer` is `zdog`, register it with Sprite.
+This illustrative configuration uses `assetPolicy` as the host's configured
+Sprite asset policy:
+
+```ts
+const service = createSprite({
+  assets: assetPolicy,
+  renderers: {
+    zdog: () => import("@fungi.computer/sprite-zdog"),
+  },
+});
+```
+
+`assetPolicy` stands for the host's configured Sprite asset policy. Admit the
+document's origin and set its byte and request limits. A local character does
+not need remote asset access.
+
+For authoring, `defineSprite` validates a trusted scene definition, `check`
+returns a compact author-time summary, and `toCharacter` converts the definition
+into a JSON character document. The resulting document contains data, not
+executable authoring code. `@fungi.computer/sprite-zdog/builtins` exports the
+base, mushroom, cat, and burger characters.
+
+For stored avatars, import `avatarSchema` or `parseAvatar(data)` from
+`@fungi.computer/sprite-zdog/avatar`. These validate against the built-in
+character controls and expressions, rather than checking only the envelope.
+`deriveAgentAvatar(member, agentColors, seed, avoid?)` uses that same catalog;
+`agentColors` is `"keep"` or `"shift"`. `avatarCatalog` is also available from
+`./catalog` for callers using Sprite's catalog-parameterized helpers.
+`memberAvatarSchema` validates the strict `{avatar, agentColors}` preference;
+`defaultMemberAvatar` supplies the uncustomized mushroom with colour shift on.
+
+## API reference
+
+See the generated [package API](docs/api/README.md),
+[authoring API](docs/api/author.md), and
+[portable document API](docs/api/portable.md). The package also exposes
+individual built-ins through `@fungi.computer/sprite-zdog/builtins/<name>`.
+
+## Examples and checks
+
+The local Sprite stories live in `src/*.stories.tsx`. Run the package tests
+with:
+
+```sh
+pnpm --filter @fungi.computer/sprite-zdog test
+```
+
+The authoring and portable-runtime tests cover definition validation,
+serialization, decoding, and cleanup.
+
+## Limits and errors
+
+The Zdog renderer requires a browser window and canvas. It decodes the
+character's Zdog data before creating a renderer and removes its canvas and
+animation resources when the player selection closes. Invalid scene data,
+missing expressions, or invalid palette colors fail the selection.
+
+The authoring callback is trusted code that runs while creating the portable
+document. Runtime rendering reads the resulting JSON data. It does not execute
+the authoring callback. Served documents still use Sprite's host-owned origin
+and asset limits.
+
+## Contribute and license
+
+Sprite Zdog is MIT licensed. See [`LICENSE`](LICENSE) and
+[`THIRD_PARTY_NOTICES`](THIRD_PARTY_NOTICES).

package/dist/agent-proof/moth.d.ts

@@ -0,0 +1,50 @@
+declare const moth: Readonly<{
+    readonly apiVersion: 1;
+    readonly name: "moth";
+    readonly palette: {
+        readonly body: "#eee6d3";
+        readonly ink: "#322f35";
+        readonly glow: "#f2b84b";
+    };
+    readonly build: ({ scene, color }: import("@fungi.computer/sprite-zdog/author").AuthorContext) => {
+        root: import("@fungi.computer/sprite-zdog/author").SceneNode;
+        variants: {
+            eyes: {
+                normal: import("@fungi.computer/sprite-zdog/author").SceneNode;
+            };
+        };
+    };
+    readonly expressions: {
+        readonly normal: {
+            readonly variants: {
+                readonly eyes: "normal";
+            };
+        };
+        readonly alert: {
+            readonly variants: {
+                readonly eyes: "normal";
+            };
+        };
+    };
+    readonly activities: {
+        readonly idle: {};
+        readonly listening: {};
+        readonly processing: {};
+        readonly speaking: {
+            readonly mouthCycle: readonly [{
+                readonly durationMs: 20;
+                readonly mouth: "base";
+            }];
+        };
+        readonly thinking: {};
+        readonly error: {};
+        readonly flutter: {
+            readonly motion: {
+                readonly target: "root";
+                readonly durationMs: 20;
+                readonly repeat: "yoyo";
+            };
+        };
+    };
+}>;
+export default moth;

package/dist/agent-proof/moth.js

@@ -0,0 +1,52 @@
+import { defineSprite } from "@fungi.computer/sprite-zdog/author";
+const moth = defineSprite({
+    apiVersion: 1,
+    name: "moth",
+    palette: { body: "#eee6d3", ink: "#322f35", glow: "#f2b84b" },
+    build({ scene, color }) {
+        const root = scene.group({ name: "root" });
+        const eyes = scene.group({ parent: root, name: "eyes" });
+        scene.ellipse({
+            parent: root,
+            name: "body",
+            width: 18,
+            height: 26,
+            color: color("body"),
+            fill: true,
+            stroke: false,
+        });
+        scene.ellipse({
+            parent: eyes,
+            name: "eye.left",
+            width: 3,
+            height: 5,
+            x: -4,
+            color: color("ink"),
+            fill: true,
+        });
+        scene.ellipse({
+            parent: eyes,
+            name: "eye.right",
+            width: 3,
+            height: 5,
+            x: 4,
+            color: color("ink"),
+            fill: true,
+        });
+        return { root, variants: { eyes: { normal: eyes } } };
+    },
+    expressions: {
+        normal: { variants: { eyes: "normal" } },
+        alert: { variants: { eyes: "normal" } },
+    },
+    activities: {
+        idle: {},
+        listening: {},
+        processing: {},
+        speaking: { mouthCycle: [{ durationMs: 20, mouth: "base" }] },
+        thinking: {},
+        error: {},
+        flutter: { motion: { target: "root", durationMs: 20, repeat: "yoyo" } },
+    },
+});
+export default moth;

package/dist/author.d.ts

@@ -0,0 +1,217 @@
+declare const sceneNodeBrand: unique symbol;
+/** An opaque node in a renderer-neutral Sprite scene. */
+export type SceneNode = {
+    /** Nominal marker that keeps renderer details out of the author surface. */
+    readonly [sceneNodeBrand]: true;
+};
+/** A point in Sprite scene space. */
+export type Point = {
+    /** Horizontal scene coordinate. */
+    readonly x: number;
+    /** Vertical scene coordinate. */
+    readonly y: number;
+    /** Optional depth coordinate. */
+    readonly z?: number;
+};
+/** One cubic Bezier path segment. */
+export type BezierStep = {
+    /** Two control points followed by the segment endpoint. */
+    readonly bezier: readonly [Point, Point, Point];
+};
+/** One renderer-neutral shape path segment. */
+export type PathStep = Point | BezierStep;
+/** Optional translation, rotation, or scale coordinates. */
+export type Transform = {
+    /** Optional horizontal component. */
+    readonly x?: number;
+    /** Optional vertical component. */
+    readonly y?: number;
+    /** Optional depth component. */
+    readonly z?: number;
+};
+/** Shared renderer-neutral options for one scene node. */
+export type SceneNodeOptions = {
+    /** Definition-local name used by authored references. */
+    readonly name?: string;
+    /** Parent node in the same definition. */
+    readonly parent?: SceneNode;
+    /** Horizontal translation that takes precedence over `translate.x`. */
+    readonly x?: number;
+    /** Vertical translation that takes precedence over `translate.y`. */
+    readonly y?: number;
+    /** Depth translation that takes precedence over `translate.z`. */
+    readonly z?: number;
+    /** Translation components not supplied by the direct coordinates. */
+    readonly translate?: Transform;
+    /** Rotation around each scene axis, in radians. */
+    readonly rotate?: Transform;
+    /** Scale applied along each scene axis. */
+    readonly scale?: Transform;
+    /** Whether the node participates in rendering. */
+    readonly visible?: boolean;
+    /** Literal paint or an opaque reference returned by `color`. */
+    readonly color?: string;
+    /** A false stroke keeps a solid primitive edge-free, as in Zdog fills. */
+    readonly stroke?: number | false;
+    readonly fill?: boolean;
+    /** Optional rear/forward surface palette slots for 3D solids. */
+    readonly backface?: string;
+    /** Paint used for a primitive's front face when supported. */
+    readonly frontFace?: string;
+    /** Whether supported primitives update child depth ordering. */
+    readonly updateSort?: boolean;
+};
+/** Renderer-neutral options for a freeform shape. */
+export type PathOptions = {
+    /** Ordered points and cubic Bezier segments in the path. */
+    readonly path?: readonly PathStep[];
+    /** Whether the renderer closes the path. */
+    readonly closed?: boolean;
+} & SceneNodeOptions;
+/** Renderer-neutral options for an ellipse. */
+export type EllipseOptions = {
+    /** Horizontal diameter. */
+    readonly width: number;
+    /** Vertical diameter. */
+    readonly height: number;
+} & SceneNodeOptions;
+/** Renderer-neutral options for a hemisphere. */
+export type HemisphereOptions = {
+    /** Diameter of the hemisphere's base. */
+    readonly diameter: number;
+} & SceneNodeOptions;
+/** Renderer-neutral options for a cylinder. */
+export type CylinderOptions = {
+    /** Diameter of the cylinder's circular faces. */
+    readonly diameter: number;
+    /** Distance between the cylinder's faces. */
+    readonly length: number;
+} & SceneNodeOptions;
+/** The complete renderer-neutral scene authoring surface. */
+export type SceneBuilder = {
+    /** Create a grouping node. */
+    group(options?: SceneNodeOptions): SceneNode;
+    /** Create a freeform path node. */
+    path(options: PathOptions): SceneNode;
+    /** Create an ellipse node. */
+    ellipse(options: EllipseOptions): SceneNode;
+    /** Create a hemisphere node. */
+    hemisphere(options: HemisphereOptions): SceneNode;
+    /** Create a cylinder node. */
+    cylinder(options: CylinderOptions): SceneNode;
+};
+/** A named motion applied while presenting a Sprite. */
+export type MotionSpec = {
+    /** Name of the scene node targeted by the motion. */
+    readonly target: string;
+    /** Authored translation change. */
+    readonly translate?: Transform;
+    /** Authored rotation change. */
+    readonly rotate?: Transform;
+    /** Duration of one motion pass in milliseconds. */
+    readonly durationMs?: number;
+    /** Repetition mode for the motion. */
+    readonly repeat?: "none" | "loop" | "yoyo";
+};
+/** The standard presentation activity names accepted by every Sprite. */
+export type StandardActivity = "idle" | "listening" | "processing" | "speaking" | "thinking" | "error";
+/** Variant selections applied to one expression or activity. */
+export type StateGeometry = {
+    /** Expression selected by an activity. */
+    readonly expression?: string;
+    /** Value selected from the `eyes` variant channel. */
+    readonly eyes?: string;
+    /** Value selected from the `mouth` variant channel. */
+    readonly mouth?: string;
+    /** Normalized blush intensity. */
+    readonly blush?: number;
+};
+/** One timed mouth state in a speaking cycle. */
+export type MouthCycleStep = {
+    /** Time spent in this mouth state, in milliseconds. */
+    readonly durationMs: number;
+    /** Mouth state shown during the step. */
+    readonly mouth: "base" | "open";
+};
+/** Presentation behavior associated with an activity. */
+export type ActivitySpec = {
+    /** Optional motion authored for the activity. */
+    readonly motion?: MotionSpec;
+    /** Optional geometry selections authored for the activity. */
+    readonly geometry?: StateGeometry;
+    /** Authored pointer-influence strength. */
+    readonly mouseInfluence?: number;
+    /** Ordered timed mouth states for the activity. */
+    readonly mouthCycle?: readonly MouthCycleStep[];
+};
+/** Variant and motion behavior associated with an expression. */
+export type ExpressionSpec = {
+    /** Fixed value selected for each variant channel. */
+    readonly variants?: Record<string, string>;
+    /** Candidate values authored for each variant channel. */
+    readonly variantChoices?: Record<string, readonly string[]>;
+    /** Normalized blush intensity. */
+    readonly blush?: number;
+    /** Optional motion authored for the expression. */
+    readonly motion?: MotionSpec;
+};
+/** The root and named variants produced by one author build. */
+export type BuildResult = {
+    /** Root node of the rendered scene tree. */
+    readonly root: SceneNode;
+    /** Definition-local nodes grouped by variant channel and value. */
+    readonly variants?: Record<string, Record<string, SceneNode>>;
+};
+/** Renderer-neutral capabilities available while authoring a Sprite. */
+export type AuthorContext = {
+    /** Scene builder valid only for the duration of `build`. */
+    readonly scene: SceneBuilder;
+    /** Create an opaque reference to an own palette slot. */
+    readonly color: (name: string) => string;
+};
+/** Input accepted by the Sprite authoring seam. */
+export type SpriteDefinitionInput = {
+    /** Version of the authoring contract used by this definition. */
+    readonly apiVersion: 1;
+    /** Human-readable Sprite definition name. */
+    readonly name: string;
+    /** Named default paints available to the author callback. */
+    readonly palette: Record<string, string>;
+    /** Construct the renderer-neutral scene and its named variants. */
+    readonly build: (context: AuthorContext) => BuildResult;
+    /** Named expression specifications; at least one is required. */
+    readonly expressions: Record<string, ExpressionSpec>;
+    /** Optional custom activity specifications. */
+    readonly activities?: Record<string, ActivitySpec>;
+    /** Initial activity and expression selected when mounted. */
+    readonly defaultPresentation?: {
+        /** Standard or custom activity selected initially. */
+        readonly activity?: string;
+        /** Declared expression selected initially. */
+        readonly expression?: string;
+    };
+};
+/** An authored Sprite definition preserving the author's input shape. */
+export type SpriteDefinition<Input extends SpriteDefinitionInput = SpriteDefinitionInput> = Readonly<Input>;
+/** A compact receipt describing one already-authored Sprite definition. */
+export type SpriteCheckResult = {
+    /** Whether the definition has completed author-time validation. */
+    readonly valid: true;
+    /** Human-readable name of the checked definition. */
+    readonly name: string;
+    /** Number of scene nodes reachable from the definition root. */
+    readonly nodeCount: number;
+    /** Expression names in author insertion order. */
+    readonly expressions: readonly string[];
+    /** Standard activities followed by unique custom activities in author order. */
+    readonly activities: readonly string[];
+    /** Variant values by channel, preserving author insertion order. */
+    readonly variants: Readonly<Record<string, readonly string[]>>;
+};
+/** The standard presentation activities every Sprite understands. */
+export declare const STANDARD_ACTIVITIES: readonly ["idle", "listening", "processing", "speaking", "thinking", "error"];
+/** Validate and freeze one renderer-neutral Sprite definition. */
+export declare function defineSprite<const Input extends SpriteDefinitionInput>(input: Input): SpriteDefinition<Input>;
+/** Return a compact, machine-readable receipt for an already authored definition. */
+export declare const check: (definition: SpriteDefinition) => SpriteCheckResult;
+export { toCharacter } from "./portable.js";