mochi-avatar 1.0.0

package/dist/core/mouth.js

@@ -0,0 +1,92 @@
+/**
+ * The single writer to her mouth.
+ *
+ * One object owns `setMouthOpen`, and that is the whole point rather than a
+ * tidiness preference. The mouth is layer 4 and is written last, so nothing
+ * above it can arbitrate between two sources -- two writers produce a mouth
+ * flickering between them at whatever rate they happen to disagree, and no
+ * layer ordering can fix it.
+ *
+ * ## Where the viseme path goes
+ *
+ * The mouth has two paths and they are not a ladder: cloud speech-to-speech
+ * carries no phoneme timings, so the envelope is the only thing available
+ * there, not a fallback. The five-vowel path belongs to a local TTS front end,
+ * whose G2P stage produces timings for free.
+ *
+ * There is deliberately no second implementation and no factory to choose
+ * between them YET. Nothing emits phoneme timings on the current road and
+ * `MochiAvatar.caps.visemes` is false, so a `VisemeMouth` would be an
+ * abstraction over one caller and a capability nobody can satisfy. When a
+ * provider reports `phonemeTimings`, it arrives as a second class behind this
+ * same interface and the choice is made ONCE -- by picking an object, never by
+ * a flag read inside a callback, which would be a branch in every frame and a
+ * place for the wrong path to be taken.
+ *
+ * ## The gate is THREE conditions, not one
+ *
+ * When that day comes, the precise path requires all of:
+ *
+ *   1. the provider emits phoneme timings,
+ *   2. the backend can render visemes (`caps.visemes`), and
+ *   3. THE LOADED MODEL carries every one of the five vowel presets.
+ *
+ * The third is the one that gets dropped, and it is the expensive one. VRM's
+ * vowel presets are optional per model, so a capable backend can load a model
+ * carrying none: routing on caps alone sends weights nowhere and leaves the
+ * mouth shut mid-word, intermittently, with every flag reporting success. RMS
+ * over the whole utterance is visibly better than four fifths of a mouth.
+ *
+ * mochi locked all three into `canUseVisemes()` in shared/avatar.ts. It is not
+ * ported here because there is nothing yet to call it -- port it together with
+ * the second driver, not before.
+ */
+import { DEFAULT_ENVELOPE, SILENT, advanceEnvelope } from './envelope.js';
+/**
+ * The RMS path.
+ *
+ * Driven once per rendered frame rather than per audio callback. Under a peer
+ * connection her voice is a remote MediaStream the browser plays itself -- no
+ * PCM reaches this process at all -- so the level arrives by sampling an
+ * analyser, which is naturally a per-frame operation. At 60Hz that is a 16ms
+ * sampling interval against a ~4Hz syllable rate, which is ample.
+ */
+export class EnvelopeMouth {
+    avatar;
+    settings;
+    state = SILENT;
+    constructor(avatar, settings = DEFAULT_ENVELOPE) {
+        this.avatar = avatar;
+        this.settings = settings;
+    }
+    observe(level, dtSeconds) {
+        this.state = advanceEnvelope(level, this.state, dtSeconds, this.settings);
+        this.avatar.setMouthOpen(this.state.mouthOpen);
+    }
+    /**
+     * Whether the envelope currently judges the signal to be speech.
+     *
+     * The one place anything outside the rig should ask that question. Reading it
+     * here rather than re-deriving it from a level means the mouth and the
+     * "is she still talking" decision can never disagree -- and they did, when
+     * the caller compared a raw RMS against a constant while this compared a peak
+     * against a learned floor.
+     */
+    get speaking() {
+        return this.state.speaking;
+    }
+    /**
+     * Shut, and forget the level -- but KEEP the learned floor and peak.
+     *
+     * The references are what make the envelope level-independent, and they are
+     * properties of this voice on this connection, not of this turn. Discarding
+     * them at every turn boundary would make her first syllable back a
+     * recalibration, which is visible: the mouth either slams or sits closed
+     * while the estimate catches up.
+     */
+    end() {
+        this.state = { ...this.state, mouthOpen: 0 };
+        this.avatar.setMouthOpen(0);
+    }
+}
+//# sourceMappingURL=mouth.js.map

package/dist/core/mouth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mouth.js","sourceRoot":"","sources":["../../src/core/mouth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,eAAe,EAAyB,MAAM,eAAe,CAAA;AAehG;;;;;;;;GAQG;AACH,MAAM,OAAO,aAAa;IAIL,MAAM;IACN,QAAQ;IAJnB,KAAK,GAAG,MAAM,CAAA;IAEtB,YACmB,MAAiB,EACjB,QAAQ,GAAqB,gBAAgB;sBAD7C,MAAM;wBACN,QAAQ;IACxB,CAAC;IAEJ,OAAO,CAAC,KAAa,EAAE,SAAiB;QACtC,IAAI,CAAC,KAAK,GAAG,eAAe,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAA;QACzE,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAA;IAChD,CAAC;IAED;;;;;;;;OAQG;IACH,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAA;IAC5B,CAAC;IAED;;;;;;;;OAQG;IACH,GAAG;QACD,IAAI,CAAC,KAAK,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,CAAC,EAAE,CAAA;QAC5C,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAA;IAC7B,CAAC;CACF"}

package/dist/core/plain.d.ts

@@ -0,0 +1,23 @@
+import type { FaceSpec } from './spec.js';
+/**
+ * The default face, and deliberately NOT a good one.
+ *
+ * An engine that renders nothing until you hand it thirty-nine numbers is an
+ * engine nobody evaluates, so there has to be a default. But the character this
+ * engine was extracted from is reserved, and shipping her as the default would
+ * hand her out with the library — so `PLAIN` is built to be visibly a different
+ * creature, along exactly the axes that identify her:
+ *
+ * | | Mochi | PLAIN |
+ * |---|---|---|
+ * | waist | 0.295, low and distinctive | 0.44, a near-symmetric egg |
+ * | shoulders | 1.86 / 2.58, asymmetric | 2.2 / 2.2, a plain ellipse |
+ * | shading | two tones, lit copy displaced | one flat tone, no displacement |
+ * | cheeks | a coral blush at 0.34 | none |
+ * | face | low on the body, small eyes | centred, larger eyes |
+ *
+ * Every one of those is a choice you are expected to replace. Start here, move
+ * the numbers, and the result is yours — that is what the format is for.
+ */
+export declare const PLAIN: FaceSpec;
+//# sourceMappingURL=plain.d.ts.map

package/dist/core/plain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plain.d.ts","sourceRoot":"","sources":["../../src/core/plain.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AAEzC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,KAAK,EAAE,QA+CnB,CAAA"}

package/dist/core/plain.js

@@ -0,0 +1,63 @@
+/**
+ * The default face, and deliberately NOT a good one.
+ *
+ * An engine that renders nothing until you hand it thirty-nine numbers is an
+ * engine nobody evaluates, so there has to be a default. But the character this
+ * engine was extracted from is reserved, and shipping her as the default would
+ * hand her out with the library — so `PLAIN` is built to be visibly a different
+ * creature, along exactly the axes that identify her:
+ *
+ * | | Mochi | PLAIN |
+ * |---|---|---|
+ * | waist | 0.295, low and distinctive | 0.44, a near-symmetric egg |
+ * | shoulders | 1.86 / 2.58, asymmetric | 2.2 / 2.2, a plain ellipse |
+ * | shading | two tones, lit copy displaced | one flat tone, no displacement |
+ * | cheeks | a coral blush at 0.34 | none |
+ * | face | low on the body, small eyes | centred, larger eyes |
+ *
+ * Every one of those is a choice you are expected to replace. Start here, move
+ * the numbers, and the result is yours — that is what the format is for.
+ */
+export const PLAIN = {
+    size: 100,
+    bodyW: 100,
+    bodyH: 92,
+    waist: 0.44,
+    upperShoulder: 2.2,
+    lowerShoulder: 2.2,
+    gripX: 0.7,
+    gripY: 0.7,
+    eyeX: 0.34,
+    eyeY: 0.55,
+    eyeHw: 5.5,
+    eyeUpper: 5.5,
+    eyeLower: 5.5,
+    eyeTilt: 0,
+    eyeRound: 2,
+    eyeGlint: 1.8,
+    gazeTravel: 0.4,
+    mouthY: 0.36,
+    mouthHw: 7,
+    mouthUpper: 0,
+    mouthLower: 2.6,
+    mouthRound: 2,
+    mouthOpenGain: 8,
+    cheekAlpha: 0,
+    cheekX: 0.6,
+    cheekY: 0.4,
+    cheekR: 10,
+    breathAmp: 0.03,
+    breathMs: 3000,
+    stiffness: 180,
+    damping: 22,
+    // Zero: the lit copy sits exactly on the shadow, so the body is one flat
+    // tone. The displaced two-tone shading is part of the reserved character.
+    shadowX: 0,
+    shadowY: 0,
+    colBody: '#b9c2cc',
+    colShadow: '#a9b3bf',
+    colInk: '#333b44',
+    colCheek: '#dd9999',
+    colGlint: '#ffffff',
+};
+//# sourceMappingURL=plain.js.map

package/dist/core/plain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plain.js","sourceRoot":"","sources":["../../src/core/plain.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,KAAK,GAAa;IAC7B,IAAI,EAAE,GAAG;IACT,KAAK,EAAE,GAAG;IACV,KAAK,EAAE,EAAE;IACT,KAAK,EAAE,IAAI;IACX,aAAa,EAAE,GAAG;IAClB,aAAa,EAAE,GAAG;IAClB,KAAK,EAAE,GAAG;IACV,KAAK,EAAE,GAAG;IAEV,IAAI,EAAE,IAAI;IACV,IAAI,EAAE,IAAI;IACV,KAAK,EAAE,GAAG;IACV,QAAQ,EAAE,GAAG;IACb,QAAQ,EAAE,GAAG;IACb,OAAO,EAAE,CAAC;IACV,QAAQ,EAAE,CAAC;IACX,QAAQ,EAAE,GAAG;IACb,UAAU,EAAE,GAAG;IAEf,MAAM,EAAE,IAAI;IACZ,OAAO,EAAE,CAAC;IACV,UAAU,EAAE,CAAC;IACb,UAAU,EAAE,GAAG;IACf,UAAU,EAAE,CAAC;IACb,aAAa,EAAE,CAAC;IAEhB,UAAU,EAAE,CAAC;IACb,MAAM,EAAE,GAAG;IACX,MAAM,EAAE,GAAG;IACX,MAAM,EAAE,EAAE;IAEV,SAAS,EAAE,IAAI;IACf,QAAQ,EAAE,IAAI;IACd,SAAS,EAAE,GAAG;IACd,OAAO,EAAE,EAAE;IAEX,yEAAyE;IACzE,0EAA0E;IAC1E,OAAO,EAAE,CAAC;IACV,OAAO,EAAE,CAAC;IAEV,OAAO,EAAE,SAAS;IAClB,SAAS,EAAE,SAAS;IACpB,MAAM,EAAE,SAAS;IACjB,QAAQ,EAAE,SAAS;IACnB,QAAQ,EAAE,SAAS;CACpB,CAAA"}

package/dist/core/spec.d.ts

@@ -0,0 +1,156 @@
+/**
+ * A face, as data.
+ *
+ * This is the plugin format. A designed avatar is a JSON file of these numbers
+ * -- no code, no assets, nothing executable. Design a face you like, save the
+ * file, and any host that embeds this engine can load it.
+ *
+ * ## Why data and not a code plugin
+ *
+ * The obvious "plugin" is a JS module implementing `AvatarBackend`, and that
+ * seam does exist (see `AvatarBackend` in `core/vocabulary`). It is not what a downloaded
+ * avatar gets to be. The renderer holds the IPC bridge that moves her window
+ * and disables click-through, and will later hold her audio stream; handing
+ * arbitrary downloaded code into that process trades a very large amount of
+ * authority for a different-shaped blob. Data cannot escalate.
+ *
+ * ## Why every field is bounded, not merely typed
+ *
+ * These numbers arrive from a file somebody else wrote. Type-checking alone
+ * accepts `waist: 50` or `bodyW: -1`, which do not throw -- they render a shape
+ * that is wrong in a way no error mentions, or divide by something near zero
+ * and produce a mochi the size of the screen. Every field therefore declares a
+ * range, and the range is checked at the boundary rather than defended against
+ * in the geometry.
+ */
+export interface FaceSpec {
+    /**
+     * How big she is on screen, as a percentage of the base scale.
+     *
+     * Part of the FACE, because "how she looks" includes how much room she takes
+     * — and because leaving it out made it a code change: `showFace` hardcoded
+     * `size: 100`, so somebody who wanted a smaller mochi had to edit
+     * TypeScript, rebuild, and hope. That is the exact thing this format exists
+     * to stop.
+     *
+     * 100 puts her `bodyW` of 100 units at `BASE_UNIT_SCALE` — about 94 CSS
+     * pixels, which is also the size v1's design handoff specified for her
+     * window.
+     */
+    readonly size: number;
+    /** FULL width, in design units. */
+    readonly bodyW: number;
+    /** FULL height. She rests on the surface, so this is not a half-extent. */
+    readonly bodyH: number;
+    /** Height of the widest point, 0..0.95. Measured 0.295 on the icon. */
+    readonly waist: number;
+    /** Superellipse exponent above the waist. Below 2 is pointier than an ellipse. */
+    readonly upperShoulder: number;
+    /** Superellipse exponent below the waist. Above 2 is fuller than an ellipse. */
+    readonly lowerShoulder: number;
+    /** How much the face follows the body's deformation. Under 1 resists it. */
+    readonly gripX: number;
+    readonly gripY: number;
+    readonly eyeX: number;
+    readonly eyeY: number;
+    readonly eyeHw: number;
+    readonly eyeUpper: number;
+    readonly eyeLower: number;
+    readonly eyeTilt: number;
+    /** Superellipse exponent for the eyes. 2 is a round dot; below sharpens. */
+    readonly eyeRound: number;
+    /**
+     * Half-extent of the catchlight -- the white block that makes an eye look lit.
+     *
+     * 0 draws none, which is the honest way to opt out: a face with no highlight
+     * is a design choice, and expressing it as a size means it needs no flag.
+     */
+    readonly eyeGlint: number;
+    readonly gazeTravel: number;
+    readonly mouthY: number;
+    readonly mouthHw: number;
+    readonly mouthUpper: number;
+    readonly mouthLower: number;
+    readonly mouthRound: number;
+    /** How far a mouthOpen of 1 pushes the lower arc down. */
+    readonly mouthOpenGain: number;
+    readonly cheekAlpha: number;
+    readonly cheekX: number;
+    readonly cheekY: number;
+    readonly cheekR: number;
+    /**
+     * How far a full inhale spreads her, on the squash channel.
+     *
+     * ONE-SIDED: the breath runs 0..1, so this is the whole excursion rather than
+     * a half-amplitude, and it only ever spreads her. It cannot stretch her
+     * taller than her resting silhouette -- see `core/idle.ts`, `breathAt`.
+     */
+    readonly breathAmp: number;
+    readonly breathMs: number;
+    readonly stiffness: number;
+    readonly damping: number;
+    /** Displacement of the LIT copy of the silhouette, as a fraction of her size. */
+    readonly shadowX: number;
+    readonly shadowY: number;
+    readonly colBody: string;
+    readonly colShadow: string;
+    readonly colInk: string;
+    readonly colCheek: string;
+    /** The catchlight. Not hardcoded white: an ink that is not near-black wants its own. */
+    readonly colGlint: string;
+}
+type NumericKey = {
+    [K in keyof FaceSpec]: FaceSpec[K] extends number ? K : never;
+}[keyof FaceSpec];
+export type ColourKey = {
+    [K in keyof FaceSpec]: FaceSpec[K] extends string ? K : never;
+}[keyof FaceSpec];
+export interface Bound {
+    readonly min: number;
+    readonly max: number;
+    /** Granularity a slider should offer. Not enforced -- a spec may be finer. */
+    readonly step: number;
+}
+/**
+ * The permitted range of every numeric field.
+ *
+ * One table, read by BOTH the validator and the tuner's sliders. Two copies
+ * would let the editor offer a value the loader rejects, which presents to a
+ * user as "I designed this and the app ignored it".
+ *
+ * Wider than the tuner's comfortable range in places: these are the bounds of
+ * what is safe to render, not of what looks good. Taste is the designer's.
+ */
+export declare const FACE_BOUNDS: Readonly<Record<NumericKey, Bound>>;
+export declare const COLOUR_KEYS: readonly ColourKey[];
+/**
+ * `#rgb` and `#rrggbb`, with or without alpha. Nothing else — see parseFaceSpec.
+ *
+ * Exported so `core/colour` can validate against the SAME pattern rather than
+ * its own copy. Two copies had already drifted apart once: one trimmed its
+ * input and the other did not, so a colour could pass validation here and be
+ * unreadable there, or the reverse.
+ */
+export declare const HEX_COLOUR: RegExp;
+export type ParseResult = {
+    readonly ok: true;
+    readonly face: FaceSpec;
+} | {
+    readonly ok: false;
+    readonly problems: readonly string[];
+};
+/**
+ * Turn something read off disk into a face, or say exactly what is wrong.
+ *
+ * Reports EVERY problem rather than the first. Someone hand-editing an avatar
+ * file wants the whole list; failing on the first field turns one round of
+ * fixing into five, and they have no way to see the rest until each is cleared.
+ *
+ * Colours are restricted to hex. CSS accepts a great deal more -- `url(...)`,
+ * `image-set(...)`, custom properties -- and a colour string reaches
+ * `fillStyle`, which is the one place in this format where a value is
+ * interpreted rather than measured.
+ */
+export declare function parseFaceSpec(value: unknown): ParseResult;
+export {};
+//# sourceMappingURL=spec.d.ts.map

package/dist/core/spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.d.ts","sourceRoot":"","sources":["../../src/core/spec.ts"],"names":[],"mappings":"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"}

package/dist/core/spec.js

@@ -0,0 +1,236 @@
+/**
+ * A face, as data.
+ *
+ * This is the plugin format. A designed avatar is a JSON file of these numbers
+ * -- no code, no assets, nothing executable. Design a face you like, save the
+ * file, and any host that embeds this engine can load it.
+ *
+ * ## Why data and not a code plugin
+ *
+ * The obvious "plugin" is a JS module implementing `AvatarBackend`, and that
+ * seam does exist (see `AvatarBackend` in `core/vocabulary`). It is not what a downloaded
+ * avatar gets to be. The renderer holds the IPC bridge that moves her window
+ * and disables click-through, and will later hold her audio stream; handing
+ * arbitrary downloaded code into that process trades a very large amount of
+ * authority for a different-shaped blob. Data cannot escalate.
+ *
+ * ## Why every field is bounded, not merely typed
+ *
+ * These numbers arrive from a file somebody else wrote. Type-checking alone
+ * accepts `waist: 50` or `bodyW: -1`, which do not throw -- they render a shape
+ * that is wrong in a way no error mentions, or divide by something near zero
+ * and produce a mochi the size of the screen. Every field therefore declares a
+ * range, and the range is checked at the boundary rather than defended against
+ * in the geometry.
+ */
+/**
+ * The permitted range of every numeric field.
+ *
+ * One table, read by BOTH the validator and the tuner's sliders. Two copies
+ * would let the editor offer a value the loader rejects, which presents to a
+ * user as "I designed this and the app ignored it".
+ *
+ * Wider than the tuner's comfortable range in places: these are the bounds of
+ * what is safe to render, not of what looks good. Taste is the designer's.
+ */
+export const FACE_BOUNDS = {
+    // The same band `clampSizePercent` enforces in `core/layout`, stated here
+    // because this is where a user-supplied value is refused.
+    size: { min: 50, max: 200, step: 5 },
+    bodyW: { min: 20, max: 400, step: 1 },
+    bodyH: { min: 20, max: 400, step: 1 },
+    // Not 1: at the very top the shape degenerates to a spike with no underside.
+    waist: { min: 0, max: 0.95, step: 0.005 },
+    // Not below 1: the superellipse becomes concave and self-intersects.
+    upperShoulder: { min: 1, max: 8, step: 0.02 },
+    lowerShoulder: { min: 1, max: 8, step: 0.02 },
+    gripX: { min: 0, max: 1, step: 0.01 },
+    gripY: { min: 0, max: 1, step: 0.01 },
+    eyeX: { min: 0, max: 1, step: 0.005 },
+    eyeY: { min: 0, max: 1, step: 0.005 },
+    eyeHw: { min: 0, max: 60, step: 0.5 },
+    eyeUpper: { min: -60, max: 60, step: 0.5 },
+    eyeLower: { min: -60, max: 60, step: 0.5 },
+    eyeTilt: { min: -1.5, max: 1.5, step: 0.01 },
+    eyeRound: { min: 0.5, max: 8, step: 0.05 },
+    // Unbounded above by the eye on purpose: the highlight is CLIPPED to the eye
+    // it sits in, so an oversized one turns the whole eye white rather than
+    // escaping it. That is a legitimate look, and no range check has to know the
+    // eye's size to permit it.
+    eyeGlint: { min: 0, max: 30, step: 0.1 },
+    gazeTravel: { min: 0, max: 2, step: 0.01 },
+    mouthY: { min: 0, max: 1, step: 0.005 },
+    mouthHw: { min: 0, max: 80, step: 0.5 },
+    mouthUpper: { min: -60, max: 60, step: 0.25 },
+    mouthLower: { min: -60, max: 60, step: 0.25 },
+    mouthRound: { min: 0.5, max: 8, step: 0.05 },
+    mouthOpenGain: { min: 0, max: 100, step: 0.5 },
+    cheekAlpha: { min: 0, max: 1, step: 0.01 },
+    cheekX: { min: 0, max: 1.5, step: 0.01 },
+    cheekY: { min: 0, max: 1, step: 0.01 },
+    cheekR: { min: 0, max: 80, step: 0.5 },
+    breathAmp: { min: 0, max: 0.5, step: 0.005 },
+    // Not 0: the breath divides by the period.
+    breathMs: { min: 200, max: 20_000, step: 50 },
+    // Not 0: a spring with no stiffness never returns.
+    stiffness: { min: 1, max: 2000, step: 5 },
+    damping: { min: 0.1, max: 200, step: 1 },
+    shadowX: { min: -1, max: 1, step: 0.002 },
+    shadowY: { min: -1, max: 1, step: 0.002 },
+};
+/**
+ * Every colour field, as an exhaustive table rather than a list.
+ *
+ * `Record<ColourKey, true>` is the whole point: a list typed `ColourKey[]` is
+ * satisfied by ANY subset, so adding a sixth colour to `FaceSpec` compiled
+ * cleanly while the parser stayed unaware of it -- and the parser then reported
+ * the new field as "not a field of an avatar" and cast a face missing it to
+ * `FaceSpec` anyway. The built-in itself would have failed to load, and the
+ * tests would not have caught it because they derive their expectations from
+ * this same array.
+ *
+ * `FACE_BOUNDS` above is exhaustive over the numeric keys for exactly this
+ * reason. The colours were the half of the format that had no such guard.
+ */
+const COLOUR_FIELDS = {
+    colBody: true,
+    colShadow: true,
+    colInk: true,
+    colCheek: true,
+    colGlint: true,
+};
+export const COLOUR_KEYS = Object.keys(COLOUR_FIELDS);
+/**
+ * `#rgb` and `#rrggbb`, with or without alpha. Nothing else — see parseFaceSpec.
+ *
+ * Exported so `core/colour` can validate against the SAME pattern rather than
+ * its own copy. Two copies had already drifted apart once: one trimmed its
+ * input and the other did not, so a colour could pass validation here and be
+ * unreadable there, or the reverse.
+ */
+export const HEX_COLOUR = /^#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+/** Long enough for any label a person writes, short enough not to be a payload. */
+const NAME_MAX = 80;
+/**
+ * A value, rendered for an error message, without throwing.
+ *
+ * `JSON.stringify` throws on a BigInt -- so the error path itself could throw,
+ * and `parseFaceSpec` would break the one promise its signature makes: that it
+ * returns a verdict. Disk JSON cannot carry a BigInt, but the parameter is
+ * `unknown` and the export is public, so the contract has to hold for whatever
+ * arrives, not for what is expected to.
+ */
+function describe(value) {
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (typeof value === 'bigint')
+        return `${value}n`;
+    if (typeof value === 'object' && value !== null)
+        return Array.isArray(value) ? 'an array' : 'an object';
+    return String(value);
+}
+/**
+ * An error, as a string, without throwing a second time.
+ *
+ * `String(error)` is not safe on arbitrary input: a null-prototype object has
+ * no `toString`, and a Proxy can throw from one. That made the whole point of
+ * the catch below reachable-but-broken — the one function whose contract is
+ * "always returns a verdict" could still take its caller down.
+ */
+function describeError(error) {
+    try {
+        return String(error);
+    }
+    catch {
+        return 'an error that could not be described';
+    }
+}
+/**
+ * Turn something read off disk into a face, or say exactly what is wrong.
+ *
+ * Reports EVERY problem rather than the first. Someone hand-editing an avatar
+ * file wants the whole list; failing on the first field turns one round of
+ * fixing into five, and they have no way to see the rest until each is cleared.
+ *
+ * Colours are restricted to hex. CSS accepts a great deal more -- `url(...)`,
+ * `image-set(...)`, custom properties -- and a colour string reaches
+ * `fillStyle`, which is the one place in this format where a value is
+ * interpreted rather than measured.
+ */
+export function parseFaceSpec(value) {
+    try {
+        return readFaceSpec(value);
+    }
+    catch (error) {
+        // The signature promises a VERDICT for any `unknown`, and reading a
+        // property is not guaranteed to be safe: a getter or a Proxy can throw, and
+        // then the one function whose job is to decide whether something is a face
+        // takes the caller down with it. Today's inputs are `JSON.parse` output and
+        // structured-cloned IPC payloads, neither of which can carry a getter --
+        // which is exactly why nothing would have found this until the day some
+        // caller passed a live object.
+        return { ok: false, problems: [`the avatar could not be read: ${describeError(error)}`] };
+    }
+}
+function readFaceSpec(value) {
+    const problems = [];
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return { ok: false, problems: ['the avatar file must contain a JSON object'] };
+    }
+    const source = value;
+    const face = {};
+    for (const [key, bound] of Object.entries(FACE_BOUNDS)) {
+        const raw = source[key];
+        if (raw === undefined) {
+            problems.push(`${key} is missing`);
+            continue;
+        }
+        if (typeof raw !== 'number' || !Number.isFinite(raw)) {
+            problems.push(`${key} must be a finite number, got ${describe(raw)}`);
+            continue;
+        }
+        if (raw < bound.min || raw > bound.max) {
+            problems.push(`${key} must be between ${bound.min} and ${bound.max}, got ${raw}`);
+            continue;
+        }
+        face[key] = raw;
+    }
+    for (const key of COLOUR_KEYS) {
+        const raw = source[key];
+        if (raw === undefined) {
+            problems.push(`${key} is missing`);
+            continue;
+        }
+        if (typeof raw !== 'string' || !HEX_COLOUR.test(raw)) {
+            problems.push(`${key} must be a hex colour like #8ec8a8, got ${describe(raw)}`);
+            continue;
+        }
+        face[key] = raw;
+    }
+    // `name` is a label for whoever is editing the file. It is deliberately NOT
+    // part of `FaceSpec` -- nothing renders it, and `resolveAvatar` identifies an
+    // avatar by filename -- but it is still validated, because "accepted and
+    // discarded" and "accepted, wrong, and discarded" look identical from the
+    // outside. A `name` of `12345` used to pass silently; now it is a problem
+    // reported alongside every other, which is the promise this parser makes.
+    if ('name' in source) {
+        const name = source['name'];
+        if (typeof name !== 'string' || name.trim() === '') {
+            problems.push(`name must be a non-empty label, got ${describe(name)}`);
+        }
+        else if (name.length > NAME_MAX) {
+            problems.push(`name must be at most ${NAME_MAX} characters`);
+        }
+    }
+    // Unknown keys are reported, not rejected. A typo like `eyeWith` is silently
+    // ignored otherwise, and the designer sees their change do nothing.
+    const known = new Set([...Object.keys(FACE_BOUNDS), ...COLOUR_KEYS]);
+    for (const key of Object.keys(source)) {
+        if (!known.has(key) && key !== 'name')
+            problems.push(`${key} is not a field of an avatar`);
+    }
+    if (problems.length > 0)
+        return { ok: false, problems };
+    return { ok: true, face: face };
+}
+//# sourceMappingURL=spec.js.map

package/dist/core/spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.js","sourceRoot":"","sources":["../../src/core/spec.ts"],"names":[],"mappings":"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"}

package/dist/core/spring.d.ts

@@ -0,0 +1,53 @@
+/**
+ * A second-order spring.
+ *
+ * The reason this exists rather than the one-pole filter used elsewhere: a
+ * first-order system approaches its target and stops. It CANNOT overshoot, and
+ * overshoot is what reads as mass. A mochi that gets squashed should wobble
+ * past centre and settle; one that eases back looks like a scaling picture.
+ *
+ * Pure arithmetic, no clock. The caller owns time, which is what lets the same
+ * code run in a render loop and in a test that advances a number.
+ */
+export interface SpringConfig {
+    /** Pull toward the target. Higher is snappier. */
+    readonly stiffness: number;
+    /** Resistance. Below ~2*sqrt(stiffness) the spring is underdamped and overshoots. */
+    readonly damping: number;
+}
+export declare const DEFAULT_SPRING: SpringConfig;
+/**
+ * Longest step the integrator will take, in seconds.
+ *
+ * Semi-implicit Euler is only conditionally stable: past roughly 2/sqrt(k) the
+ * correction overshoots further than the error it was correcting and the value
+ * diverges to infinity within a few frames. A backgrounded window, a breakpoint
+ * or a laptop waking from sleep all deliver exactly that -- a dt of seconds.
+ *
+ * Clamping means a long gap is under-integrated (she resumes from where she
+ * was, a little behind) rather than exploding. Under-integration is invisible;
+ * divergence paints a mochi the size of the screen and then NaN, after which
+ * every subsequent frame is blank with nothing in the log to say why.
+ */
+export declare const MAX_STEP_SECONDS: number;
+export declare class Spring {
+    private position;
+    private velocity;
+    constructor(initial?: number);
+    /** The current value, without advancing time. */
+    get value(): number;
+    /**
+     * Advance by `dtSeconds` toward `target` and return the new value.
+     *
+     * Non-finite inputs are ignored rather than propagated: one NaN reaching the
+     * velocity would poison the spring permanently, and the symptom -- she simply
+     * stops moving, forever, from an arbitrary later frame -- points nowhere near
+     * the frame that caused it.
+     */
+    step(dtSeconds: number, target: number, config?: SpringConfig): number;
+    /** Jump to a value and kill the velocity. For teleports, not for animation. */
+    snap(value: number): void;
+    /** True once the spring has effectively stopped, so a caller can skip work. */
+    isAtRest(target: number, epsilon?: number): boolean;
+}
+//# sourceMappingURL=spring.d.ts.map

package/dist/core/spring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spring.d.ts","sourceRoot":"","sources":["../../src/core/spring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,YAAY;IAC3B,kDAAkD;IAClD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,qFAAqF;IACrF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,eAAO,MAAM,cAAc,EAAE,YAA8C,CAAA;AAE3E;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB,QAAS,CAAA;AAEtC,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,QAAQ,CAAI;IAEpB,YAAY,OAAO,SAAI,EAEtB;IAED,iDAAiD;IACjD,IAAI,KAAK,IAAI,MAAM,CAElB;IAED;;;;;;;OAOG;IACH,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,YAA6B,GAAG,MAAM,CAWrF;IAED,+EAA+E;IAC/E,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAIxB;IAED,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,SAAO,GAAG,OAAO,CAEhD;CACF"}