@fungi.computer/sprite 0.0.0-stage → 0.0.1

package/dist/controls.d.ts

@@ -0,0 +1,32 @@
+import * as z from "zod";
+/** Portable editor descriptors; native input bindings belong to each renderer. */
+export declare const controlSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"number">;
+    label: z.ZodString;
+    default: z.ZodNumber;
+    min: z.ZodNumber;
+    max: z.ZodNumber;
+    step: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"choice">;
+    label: z.ZodString;
+    default: z.ZodString;
+    options: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"color">;
+    label: z.ZodString;
+    default: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"boolean">;
+    label: z.ZodString;
+    default: z.ZodBoolean;
+}, z.core.$strict>], "type">;
+/** A validated, character-owned customization control. */
+export type Control = z.infer<typeof controlSchema>;
+/** Values saved by the shell; no renderer objects or transient activity. */
+export type Appearance = Readonly<Record<string, string | number | boolean>>;
+/** Validate the complete appearance before applying any native updates. */
+export declare function resolveAppearance(controls: Readonly<Record<string, Control>>, overrides?: Appearance): Appearance;

package/dist/controls.js

@@ -0,0 +1,64 @@
+import * as z from "zod";
+const label = z.string().trim().min(1);
+const color = z.string().regex(/^#[0-9a-f]{6}$/i);
+const numberControl = z
+    .strictObject({
+    type: z.literal("number"),
+    label,
+    default: z.number(),
+    min: z.number(),
+    max: z.number(),
+    step: z.number().positive().optional(),
+})
+    .refine((control) => control.min <= control.default && control.default <= control.max, {
+    message: "Number control default must be within its bounds",
+});
+const choiceControl = z
+    .strictObject({
+    type: z.literal("choice"),
+    label,
+    default: z.string(),
+    options: z.array(z.strictObject({ value: z.string(), label })).min(1),
+})
+    .refine((control) => control.options.some((option) => option.value === control.default) &&
+    new Set(control.options.map((option) => option.value)).size ===
+        control.options.length, {
+    message: "Choice control needs unique options and a declared default",
+});
+/** Portable editor descriptors; native input bindings belong to each renderer. */
+export const controlSchema = z.discriminatedUnion("type", [
+    numberControl,
+    choiceControl,
+    z.strictObject({ type: z.literal("color"), label, default: color }),
+    z.strictObject({ type: z.literal("boolean"), label, default: z.boolean() }),
+]);
+/** Validate the complete appearance before applying any native updates. */
+export function resolveAppearance(controls, overrides = {}) {
+    for (const key of Object.keys(overrides)) {
+        if (!Object.hasOwn(controls, key))
+            throw new Error(`Unknown appearance control: ${key}`);
+    }
+    return Object.fromEntries(Object.entries(controls).map(([key, control]) => {
+        const value = Object.hasOwn(overrides, key)
+            ? overrides[key]
+            : control.default;
+        switch (control.type) {
+            case "number":
+                return [
+                    key,
+                    z.number().min(control.min).max(control.max).parse(value),
+                ];
+            case "color":
+                return [key, color.parse(value)];
+            case "boolean":
+                return [key, z.boolean().parse(value)];
+            case "choice": {
+                const selected = z.string().parse(value);
+                if (!control.options.some((option) => option.value === selected)) {
+                    throw new Error(`Unknown choice for ${key}: ${selected}`);
+                }
+                return [key, selected];
+            }
+        }
+    }));
+}

package/dist/customization.d.ts

@@ -0,0 +1,21 @@
+import * as z from "zod";
+/**
+ * What a person saves about their Sprite. Hosts parse stored values with this
+ * schema at their boundary; character controls still validate `appearance`
+ * against the selected document when it is presented.
+ */
+export declare const customizationSchema: z.ZodObject<{
+    appearance: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    renderStyle: z.ZodDefault<z.ZodEnum<{
+        plain: "plain";
+        pencil: "pencil";
+        manga: "manga";
+        riso: "riso";
+        halftone: "halftone";
+        blueprint: "blueprint";
+        crt: "crt";
+        watercolor: "watercolor";
+    }>>;
+}, z.core.$strict>;
+/** A parsed, saved Sprite customization. */
+export type Customization = z.infer<typeof customizationSchema>;

package/dist/customization.js

@@ -0,0 +1,13 @@
+import * as z from "zod";
+import { renderStyleSchema } from "./render-style.js";
+/**
+ * What a person saves about their Sprite. Hosts parse stored values with this
+ * schema at their boundary; character controls still validate `appearance`
+ * against the selected document when it is presented.
+ */
+export const customizationSchema = z.strictObject({
+    appearance: z
+        .record(z.string().min(1), z.union([z.string(), z.number(), z.boolean()]))
+        .optional(),
+    renderStyle: renderStyleSchema.default("plain"),
+});

package/dist/document.d.ts

@@ -0,0 +1,43 @@
+import * as z from "zod";
+/** Shared envelope only. The selected adapter must decode data before use. */
+export declare const characterSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    name: z.ZodString;
+    renderer: z.ZodString;
+    controls: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"number">;
+        label: z.ZodString;
+        default: z.ZodNumber;
+        min: z.ZodNumber;
+        max: z.ZodNumber;
+        step: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"choice">;
+        label: z.ZodString;
+        default: z.ZodString;
+        options: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"color">;
+        label: z.ZodString;
+        default: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"boolean">;
+        label: z.ZodString;
+        default: z.ZodBoolean;
+    }, z.core.$strict>], "type">>>;
+    poster: z.ZodOptional<z.ZodString>;
+    data: z.ZodJSONSchema;
+}, z.core.$strict>;
+/** A portable character, with renderer data still awaiting its native decoder. */
+export type CharacterDocument = z.infer<typeof characterSchema>;
+/** Domain key for a character installed by the host. */
+export declare const localCharacterSourceSchema: z.ZodObject<{
+    local: z.ZodString;
+}, z.core.$strict>;
+/** A served document URL or a host-installed character key. */
+export type CharacterSource = string | {
+    readonly local: string;
+};

package/dist/document.js

@@ -0,0 +1,15 @@
+import * as z from "zod";
+import { controlSchema } from "./controls.js";
+/** Shared envelope only. The selected adapter must decode data before use. */
+export const characterSchema = z.strictObject({
+    version: z.literal(1),
+    name: z.string().trim().min(1),
+    renderer: z.string().trim().min(1),
+    controls: z.record(z.string().min(1), controlSchema).default({}),
+    poster: z.string().min(1).optional(),
+    data: z.json(),
+});
+/** Domain key for a character installed by the host. */
+export const localCharacterSourceSchema = z.strictObject({
+    local: z.string().trim().min(1),
+});

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { createSprite } from "./player.js";
+export type { AvatarPlayer, AvatarPresentation, EffectivePresentation, LocalCharacter, NativePlayer, NativePresentation, PlayerState, Renderer, RendererContext, SpriteOptions, SpriteService, } from "./player.js";
+export { characterSchema } from "./document.js";
+export type { CharacterDocument, CharacterSource } from "./document.js";
+export { controlSchema, resolveAppearance } from "./controls.js";
+export type { Appearance, Control } from "./controls.js";
+export type { Asset, AssetPolicy } from "./assets.js";
+export { createRenderStyleLayer, renderStyleLabels, renderStyles, renderStyleSchema, } from "./render-style.js";
+export type { RenderStyle, RenderStyleLayer } from "./render-style.js";
+export { customizationSchema } from "./customization.js";
+export type { Customization } from "./customization.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { createSprite } from "./player.js";
+export { characterSchema } from "./document.js";
+export { controlSchema, resolveAppearance } from "./controls.js";
+export { createRenderStyleLayer, renderStyleLabels, renderStyles, renderStyleSchema, } from "./render-style.js";
+export { customizationSchema } from "./customization.js";

package/dist/ink.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Ink drawings: traced manga strokes drawn on the page, stroke by stroke, with
+ * a little hand wobble. Screentone dots sprinkle in after the linework and
+ * coral goes down last. Plain Canvas 2D, so there is nothing else to load.
+ */
+/**
+ * Traced art: flat [x, y, width, ...] strokes, solid fills as solids (an outer
+ * loop then its holes, each a flat [x, y, ...] list, filled even-odd), and a
+ * flat [x, y, r, ...] screentone dot field.
+ */
+export type InkArt = Readonly<{
+    width: number;
+    height: number;
+    ink: readonly (readonly number[])[];
+    coral: readonly (readonly number[])[];
+    fills?: Readonly<{
+        ink: readonly InkSolid[];
+        coral: readonly InkSolid[];
+    }>;
+    dots: readonly number[];
+}>;
+/** One filled solid: its outer loop first, then any holes. */
+export type InkSolid = readonly (readonly number[])[];
+/** Colours as CSS colour strings; the caller reads them from its theme. */
+export type InkPalette = Readonly<{
+    ink: string;
+    coral: string;
+}>;
+/** Options accepted by mountInkDrawing. */
+export type InkDrawingOptions = Readonly<{
+    art: InkArt;
+    palette: () => InkPalette;
+    /** Seconds for the whole drawing. Defaults to 2.5. */
+    duration?: number;
+    /** Wobble amplitude in art pixels. Defaults to 0.9. */
+    wobble?: number;
+    /** Seed for a repeatable hand. */
+    seed?: number;
+}>;
+/** A mounted drawing. `redraw` repaints (after a theme change); `destroy` removes it. */
+export type InkDrawing = Readonly<{
+    redraw: () => void;
+    destroy: () => void;
+}>;
+/**
+ * Draw `art` into a canvas that fills `host`'s width at the art's aspect ratio.
+ * Drawing starts when the host scrolls into view and pauses off screen.
+ * Reduced motion paints the finished drawing at once.
+ */
+export declare function mountInkDrawing(host: HTMLElement, options: InkDrawingOptions): InkDrawing;

package/dist/ink.js

@@ -0,0 +1,225 @@
+/**
+ * Ink drawings: traced manga strokes drawn on the page, stroke by stroke, with
+ * a little hand wobble. Screentone dots sprinkle in after the linework and
+ * coral goes down last. Plain Canvas 2D, so there is nothing else to load.
+ */
+function random(seed) {
+    let state = seed >>> 0;
+    return () => {
+        state = (state + 0x6d2b79f5) >>> 0;
+        let t = state;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/** Every stroke broken into wobbled segments, in drawing order. */
+function segmentsOf(art, wobble, seed) {
+    const rand = random(seed);
+    const out = [];
+    const add = (stroke, coral) => {
+        // One slow drift per stroke plus a little jitter per point reads as a hand.
+        const phase = rand() * Math.PI * 2;
+        const drift = wobble * (0.5 + rand());
+        const points = [];
+        for (let index = 0; index + 2 < stroke.length; index += 3) {
+            const step = index / 3;
+            const bend = Math.sin(phase + step * 0.35) * drift;
+            points.push([
+                (stroke[index] ?? 0) + bend + (rand() - 0.5) * wobble * 0.4,
+                (stroke[index + 1] ?? 0) + bend * 0.6 + (rand() - 0.5) * wobble * 0.4,
+                (stroke[index + 2] ?? 1) * (0.85 + rand() * 0.3),
+            ]);
+        }
+        for (let index = 1; index < points.length; index += 1) {
+            const a = points[index - 1];
+            const b = points[index];
+            if (!a || !b)
+                continue;
+            out.push({
+                x0: a[0],
+                y0: a[1],
+                x1: b[0],
+                y1: b[1],
+                width: (a[2] + b[2]) / 2,
+                coral,
+            });
+        }
+    };
+    for (const stroke of art.ink)
+        add(stroke, false);
+    const inkCount = out.length;
+    for (const stroke of art.coral)
+        add(stroke, true);
+    // Ink first, then coral: the order the brief asks for.
+    return [...out.slice(0, inkCount), ...out.slice(inkCount)];
+}
+function prefersStill(view) {
+    return view.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+/**
+ * Draw `art` into a canvas that fills `host`'s width at the art's aspect ratio.
+ * Drawing starts when the host scrolls into view and pauses off screen.
+ * Reduced motion paints the finished drawing at once.
+ */
+export function mountInkDrawing(host, options) {
+    const { art, palette, duration = 2.5, wobble = 0.9, seed = 11 } = options;
+    const view = host.ownerDocument.defaultView;
+    if (!view)
+        throw new Error("Ink drawings need a browser window");
+    const canvas = host.ownerDocument.createElement("canvas");
+    canvas.setAttribute("aria-hidden", "true");
+    canvas.style.display = "block";
+    canvas.style.width = "100%";
+    canvas.style.height = "auto";
+    canvas.style.aspectRatio = `${String(art.width)} / ${String(art.height)}`;
+    host.append(canvas);
+    const context = canvas.getContext("2d");
+    if (!context)
+        throw new Error("Canvas 2D is unavailable");
+    const segments = segmentsOf(art, wobble, seed);
+    const inkFills = art.fills?.ink ?? [];
+    const coralFills = art.fills?.coral ?? [];
+    const dotCount = art.dots.length / 3;
+    // Share of the timeline for each pass: linework, solid ink, screentone, coral.
+    const phases = { lines: 0.5, fills: 0.15, dots: 0.15 };
+    let colours = palette();
+    let drawnSegments = 0;
+    let drawnInkSolids = 0;
+    let drawnCoralSolids = 0;
+    let drawnDots = 0;
+    let elapsed = 0;
+    let frame = 0;
+    let last = 0;
+    let visible = false;
+    const size = () => {
+        const scale = Math.min(view.devicePixelRatio || 1, 2);
+        const cssWidth = host.clientWidth || art.width;
+        canvas.width = Math.round(cssWidth * scale);
+        canvas.height = Math.round((cssWidth * scale * art.height) / art.width);
+        context.setTransform(canvas.width / art.width, 0, 0, canvas.height / art.height, 0, 0);
+        context.lineCap = "round";
+        context.lineJoin = "round";
+    };
+    const drawSegments = (until) => {
+        for (; drawnSegments < until; drawnSegments += 1) {
+            const segment = segments[drawnSegments];
+            if (!segment)
+                break;
+            context.strokeStyle = segment.coral ? colours.coral : colours.ink;
+            context.lineWidth = segment.width;
+            context.beginPath();
+            context.moveTo(segment.x0, segment.y0);
+            context.lineTo(segment.x1, segment.y1);
+            context.stroke();
+        }
+    };
+    const drawDots = (until) => {
+        context.fillStyle = colours.ink;
+        for (; drawnDots < until; drawnDots += 1) {
+            const x = art.dots[drawnDots * 3] ?? 0;
+            const y = art.dots[drawnDots * 3 + 1] ?? 0;
+            const r = art.dots[drawnDots * 3 + 2] ?? 1;
+            context.beginPath();
+            context.arc(x, y, Math.max(0.6, r), 0, Math.PI * 2);
+            context.fill();
+        }
+    };
+    // Solid areas go down one closed solid at a time, holes cut even-odd.
+    const drawSolids = (solids, from, until, colour) => {
+        context.fillStyle = colour;
+        for (let index = from; index < until; index += 1) {
+            const solid = solids[index];
+            if (!solid)
+                continue;
+            context.beginPath();
+            for (const loop of solid) {
+                context.moveTo(loop[0] ?? 0, loop[1] ?? 0);
+                for (let point = 2; point + 1 < loop.length; point += 2)
+                    context.lineTo(loop[point] ?? 0, loop[point + 1] ?? 0);
+                context.closePath();
+            }
+            context.fill("evenodd");
+        }
+        return Math.max(from, until);
+    };
+    const inkSegments = segments.findIndex((segment) => segment.coral);
+    const inkEnd = inkSegments === -1 ? segments.length : inkSegments;
+    const share = (progress, start, length) => Math.min(1, Math.max(0, (progress - start) / length));
+    const paint = (progress) => {
+        drawSegments(Math.floor(inkEnd * share(progress, 0, phases.lines)));
+        drawnInkSolids = drawSolids(inkFills, drawnInkSolids, Math.floor(inkFills.length * share(progress, phases.lines, phases.fills)), colours.ink);
+        const dotsStart = phases.lines + phases.fills;
+        drawDots(Math.floor(dotCount * share(progress, dotsStart, phases.dots)));
+        const coralStart = dotsStart + phases.dots;
+        const coral = share(progress, coralStart, 1 - coralStart);
+        if (coral > 0) {
+            drawSegments(inkEnd + Math.floor((segments.length - inkEnd) * coral));
+            drawnCoralSolids = drawSolids(coralFills, drawnCoralSolids, Math.floor(coralFills.length * coral), colours.coral);
+        }
+    };
+    const finish = () => {
+        elapsed = duration;
+        paint(1);
+    };
+    const reset = () => {
+        size();
+        context.clearRect(0, 0, art.width, art.height);
+        drawnSegments = 0;
+        drawnInkSolids = 0;
+        drawnCoralSolids = 0;
+        drawnDots = 0;
+    };
+    const tick = (now) => {
+        frame = 0;
+        if (!visible)
+            return;
+        elapsed += Math.min(0.1, (now - (last || now)) / 1000);
+        last = now;
+        paint(Math.min(1, elapsed / duration));
+        if (elapsed < duration)
+            frame = view.requestAnimationFrame(tick);
+    };
+    const play = () => {
+        if (frame || elapsed >= duration)
+            return;
+        last = 0;
+        frame = view.requestAnimationFrame(tick);
+    };
+    reset();
+    if (prefersStill(view))
+        finish();
+    const observer = new view.IntersectionObserver((entries) => {
+        visible = entries.some((entry) => entry.isIntersecting);
+        if (visible)
+            play();
+        else if (frame) {
+            view.cancelAnimationFrame(frame);
+            frame = 0;
+        }
+    }, { threshold: 0.2 });
+    observer.observe(host);
+    const redraw = () => {
+        colours = palette();
+        reset();
+        paint(Math.min(1, elapsed / duration));
+    };
+    let lastWidth = host.clientWidth;
+    const resized = new view.ResizeObserver(() => {
+        if (host.clientWidth === lastWidth)
+            return;
+        lastWidth = host.clientWidth;
+        redraw();
+    });
+    resized.observe(host);
+    return {
+        redraw,
+        destroy: () => {
+            observer.disconnect();
+            resized.disconnect();
+            if (frame)
+                view.cancelAnimationFrame(frame);
+            canvas.remove();
+        },
+    };
+}

package/dist/mycelium.d.ts

@@ -0,0 +1,139 @@
+/**
+ * A living mycelium field: hyphae grow slowly across a host element and coral
+ * nodes pulse when something finishes. Rendered with Pixi 8, which the host
+ * loads lazily and passes in, so Sprite itself never bundles Pixi.
+ */
+/** The slice of Pixi 8's Graphics this field draws with. */
+export type PixiGraphics = {
+    moveTo(x: number, y: number): PixiGraphics;
+    lineTo(x: number, y: number): PixiGraphics;
+    stroke(style: {
+        width: number;
+        color: string;
+        alpha: number;
+        cap: "round";
+    }): PixiGraphics;
+    circle(x: number, y: number, radius: number): PixiGraphics;
+    fill(style: {
+        color: string;
+    }): PixiGraphics;
+    clear(): PixiGraphics;
+    position: {
+        set(x: number, y: number): void;
+    };
+    scale: {
+        set(value: number): void;
+    };
+    alpha: number;
+    destroy(): void;
+};
+/** A Pixi render texture this field bakes threads into. */
+export type PixiTexture = {
+    destroy(destroySource?: boolean): void;
+};
+/** The slice of Pixi 8's Application this field drives. */
+export type PixiApplication<Texture extends PixiTexture = PixiTexture> = {
+    init(options: {
+        resizeTo: HTMLElement;
+        backgroundAlpha: number;
+        antialias: boolean;
+        autoDensity: boolean;
+        resolution: number;
+        preference: "webgl";
+    }): Promise<void>;
+    canvas: HTMLCanvasElement;
+    screen: {
+        width: number;
+        height: number;
+    };
+    renderer: {
+        resolution: number;
+        render(options: {
+            container: PixiGraphics;
+            target: Texture;
+            clear: boolean;
+        }): void;
+    };
+    stage: {
+        addChild(...children: unknown[]): void;
+    };
+    ticker: {
+        deltaMS: number;
+        add(listener: () => void): void;
+        start(): void;
+        stop(): void;
+    };
+    render(): void;
+    destroy(rendererOptions: {
+        removeView: boolean;
+    }, options: {
+        children: boolean;
+    }): void;
+};
+/** The Pixi 8 module surface this field needs; pass `await import("pixi.js")`. */
+export type PixiModule<Texture extends PixiTexture = PixiTexture> = {
+    Application: new () => PixiApplication<Texture>;
+    Container: new () => {
+        addChild(...children: unknown[]): void;
+    };
+    Graphics: new () => PixiGraphics;
+    Sprite: new (texture: Texture) => {
+        texture: Texture;
+    };
+    RenderTexture: {
+        create(options: {
+            width: number;
+            height: number;
+            resolution: number;
+        }): Texture;
+    };
+};
+/** Colors as CSS color strings; the caller reads them from its theme. */
+export type MyceliumPalette = Readonly<{
+    thread: string;
+    node: string;
+}>;
+/** Options accepted by mountMycelium. */
+export type MyceliumOptions<Texture extends PixiTexture = PixiTexture> = Readonly<{
+    /** The Pixi 8 module, loaded by the host. */
+    pixi: PixiModule<Texture>;
+    palette: MyceliumPalette;
+    /** Seed for a repeatable network. */
+    seed?: number;
+    /** Segment budget before growth rests. Defaults to 2600. */
+    segments?: number;
+    /** Thread opacity, 0 to 1. Defaults to 0.22 so text above stays readable. */
+    threadAlpha?: number;
+    /** Mean seconds between automatic node pulses. Defaults to 2.4. */
+    pulseEvery?: number;
+    /** Starting thread width in CSS pixels. Defaults to 1.6. */
+    threadWidth?: number;
+    /**
+     * Rectangles, in host coordinates, that threads never enter (for example
+     * a headline's line boxes). Read again on every restart.
+     */
+    avoid?: () => readonly MyceliumRect[];
+    /**
+     * A focal rectangle, in host coordinates. Growth starts along its edges so
+     * the network is densest around it. Defaults to the host's bottom and sides.
+     */
+    focus?: () => MyceliumRect | null;
+}>;
+/** A rectangle in the host's coordinate space. */
+export type MyceliumRect = Readonly<{
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}>;
+/** A mounted field. `pulse` lights one node; `destroy` removes everything. */
+export type MyceliumField = Readonly<{
+    pulse: () => void;
+    destroy: () => void;
+}>;
+/**
+ * Mount a mycelium field that fills `host`. Reduced motion renders one
+ * composed, fully grown frame and never ticks. The ticker pauses while the host
+ * is off screen or the document is hidden.
+ */
+export declare function mountMycelium<Texture extends PixiTexture>(host: HTMLElement, options: MyceliumOptions<Texture>): Promise<MyceliumField>;