mochi-avatar 1.0.0

package/dist/core/layout.d.ts

@@ -0,0 +1,142 @@
+/**
+ * How big she is, and how much room her deformation needs.
+ *
+ * ## The direction of the dependency
+ *
+ * The body is the fixed thing and the CANVAS follows from it. That is the
+ * inverse of how this started: the window was 280x280 and the rig fitted her
+ * into a fraction of it, which meant the real size was an emergent property of
+ * two constants in different files, and "make her smaller" was a change to a
+ * fraction rather than to a size. Now `bodyW x bodyH` design units times a
+ * scale IS the size, and everything else is computed from it.
+ *
+ * Host-agnostic: nothing here knows about a window, a screen, or a desktop.
+ * What sizes an OS window from these numbers lives in the host application.
+ */
+import { type FaceSpec } from './spec.js';
+/**
+ * The furthest the squash channel may travel, in either direction.
+ *
+ * Lives here rather than in the rig because it is a SIZE fact before it is an
+ * animation fact: the window has to be big enough for the most deformed frame
+ * that can ever be drawn, so whoever sizes the window needs this number. The
+ * rig imports it back for the clamp that makes it true.
+ *
+ * What it cost to leave unbounded: sleepy posture at the top of a breath
+ * widened her past the window edge, and the part that did not fit was painted
+ * as two flat vertical sides.
+ */
+export declare const SQUASH_LIMIT = 0.26;
+/** The most any look may lean. `looks.ts` is checked against this by a test. */
+export declare const LEAN_LIMIT = 0.1;
+/** How much of the half-width a full lean displaces the apex by. */
+export declare const SHEAR_GAIN = 0.55;
+/**
+ * Clearance around her worst case, in DESIGN UNITS.
+ *
+ * In her own units rather than pixels, so it scales with her: at 200% the gap
+ * around her looks the same as at 50%, which a pixel margin would not.
+ */
+export declare const BREATHING_UNITS = 8;
+/**
+ * Pixels per design unit at 100%.
+ *
+ * 0.94 puts her resting body at 94 x 73 CSS pixels, which is the chosen
+ * default size. Expressed as a scale rather than as the width itself because
+ * `bodyW` belongs to the FACE — every avatar declares its own proportions, and
+ * a default stated as "94 wide" would silently mean something different for a
+ * face that is not 100 units across.
+ *
+ * 100% is the default rather than an extreme, so the 50–200% range gives room
+ * in both directions. She was previously drawn at twice this, which is what
+ * 200% now restores.
+ */
+export declare const BASE_UNIT_SCALE = 0.94;
+/**
+ * How far into a canvas the character stands, by default.
+ *
+ * A DEFAULT the host is expected to replace. The number came from one
+ * application's window and means nothing here; it survives only as the fallback
+ * for a caller that never says where the ground is. Anything with its own
+ * layout should call `setFeet` and ignore it.
+ *
+ * Why the stance is settable at all rather than fixed: a host may not be free
+ * to place its window where it likes. macOS pins a window's top edge to the
+ * work area, so a fixed standing height meant the character could never be
+ * carried close to the top of the display — dragged upward, she stopped dead in
+ * mid-air. Letting the host move the stance instead is what fixed that, and it
+ * is the general case, not a macOS special case.
+ */
+export declare const FEET_FROM_TOP = 340;
+/**
+ * Where she stands inside a canvas of a given height.
+ *
+ * ONE rule, called by the rig that draws her and by the code that anchors the
+ * bubble to her. They used to compute it separately — one as a fraction of the
+ * canvas and one as an offset from its bottom — which agree only when the
+ * canvas happens to be exactly her layout's height.
+ */
+export declare function feetY(cssHeight: number, clearance: number, feetFromTop?: number): number;
+/**
+ * What the size setting accepts, as a percentage of `BASE_UNIT_SCALE`.
+ *
+ * DERIVED from `FACE_BOUNDS.size`, which is where a user-supplied value is
+ * refused. That table's own comment states the rule — "One table, read by BOTH
+ * the validator and the tuner's sliders. Two copies would let the editor offer
+ * a value the loader rejects" — and there had come to be four copies of these
+ * three numbers: here, in `persona-change.ts` as `SIZE_BAND`, and in the
+ * shelf's size control as `BAND`.
+ *
+ * The `fallback` is genuinely this module's own: `FACE_BOUNDS` says what is
+ * PERMITTED, and what to do with a value that is not a number at all is a
+ * question only `clampSizePercent` asks.
+ */
+export declare const SIZE_PERCENT: {
+    readonly min: number;
+    readonly max: number;
+    readonly step: number;
+    readonly fallback: 100;
+};
+export interface AvatarLayout {
+    /** Pixels per design unit. */
+    readonly scale: number;
+    /** The window, and therefore the canvas, in CSS pixels. */
+    readonly width: number;
+    readonly height: number;
+    /** Where her base sits, as a fraction of the height. */
+    readonly ground: number;
+    /** Her resting body, in CSS pixels. What a person means by "how big is she". */
+    readonly bodyWidth: number;
+    readonly bodyHeight: number;
+}
+/**
+ * The widest and tallest she can ever be drawn, in design units.
+ *
+ * Deliberately conservative on the lean: the shear displaces the apex, where
+ * the body is narrowest, so adding it to the full width over-estimates. A
+ * window a few pixels too large is invisible; one a few pixels too small
+ * crops her, and that is the failure this whole calculation exists to prevent.
+ */
+export declare function worstCaseUnits(face: FaceSpec): {
+    width: number;
+    height: number;
+};
+/** Clamp a stored percentage to something renderable. */
+export declare function clampSizePercent(value: unknown): number;
+/**
+ * Everything both processes need, from a face and a size.
+ *
+ * Rounded to whole pixels because a BrowserWindow cannot be 293.7 wide — and
+ * if main rounds while the renderer does not, her base drifts off the ground
+ * line by a fraction of a pixel and the two disagree about where she is.
+ */
+export declare function layoutFor(face: FaceSpec, sizePercent: number): AvatarLayout;
+/**
+ * The largest scale whose WORST CASE still fits a canvas somebody else sized.
+ *
+ * For the tuner, which lays out its own grid of cells and cannot be told what
+ * size to be. The app never uses this — it sizes the window from `layoutFor`,
+ * which is the whole point of the inversion.
+ */
+export declare function fitToCanvas(face: FaceSpec, cssWidth: number, cssHeight: number): number;
+//# sourceMappingURL=layout.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../src/core/layout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAe,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAA;AACtD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY,OAAO,CAAA;AAEhC,gFAAgF;AAChF,eAAO,MAAM,UAAU,MAAM,CAAA;AAE7B,oEAAoE;AACpE,eAAO,MAAM,UAAU,OAAO,CAAA;AAE9B;;;;;GAKG;AACH,eAAO,MAAM,eAAe,IAAI,CAAA;AAEhC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,eAAe,OAAO,CAAA;AAEnC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,aAAa,MAAM,CAAA;AAEhC;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,SAAgB,GAAG,MAAM,CAU/F;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,YAAY;;;;uBAAoC,GAAG;CAAW,CAAA;AAE3E,MAAM,WAAW,YAAY;IAC3B,8BAA8B;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,wDAAwD;IACxD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,gFAAgF;IAChF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAMhF;AAED,yDAAyD;AACzD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAGvD;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,GAAG,YAAY,CAc3E;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAevF"}

package/dist/core/layout.js

@@ -0,0 +1,172 @@
+/**
+ * How big she is, and how much room her deformation needs.
+ *
+ * ## The direction of the dependency
+ *
+ * The body is the fixed thing and the CANVAS follows from it. That is the
+ * inverse of how this started: the window was 280x280 and the rig fitted her
+ * into a fraction of it, which meant the real size was an emergent property of
+ * two constants in different files, and "make her smaller" was a change to a
+ * fraction rather than to a size. Now `bodyW x bodyH` design units times a
+ * scale IS the size, and everything else is computed from it.
+ *
+ * Host-agnostic: nothing here knows about a window, a screen, or a desktop.
+ * What sizes an OS window from these numbers lives in the host application.
+ */
+import { FACE_BOUNDS } from './spec.js';
+/**
+ * The furthest the squash channel may travel, in either direction.
+ *
+ * Lives here rather than in the rig because it is a SIZE fact before it is an
+ * animation fact: the window has to be big enough for the most deformed frame
+ * that can ever be drawn, so whoever sizes the window needs this number. The
+ * rig imports it back for the clamp that makes it true.
+ *
+ * What it cost to leave unbounded: sleepy posture at the top of a breath
+ * widened her past the window edge, and the part that did not fit was painted
+ * as two flat vertical sides.
+ */
+export const SQUASH_LIMIT = 0.26;
+/** The most any look may lean. `looks.ts` is checked against this by a test. */
+export const LEAN_LIMIT = 0.1;
+/** How much of the half-width a full lean displaces the apex by. */
+export const SHEAR_GAIN = 0.55;
+/**
+ * Clearance around her worst case, in DESIGN UNITS.
+ *
+ * In her own units rather than pixels, so it scales with her: at 200% the gap
+ * around her looks the same as at 50%, which a pixel margin would not.
+ */
+export const BREATHING_UNITS = 8;
+/**
+ * Pixels per design unit at 100%.
+ *
+ * 0.94 puts her resting body at 94 x 73 CSS pixels, which is the chosen
+ * default size. Expressed as a scale rather than as the width itself because
+ * `bodyW` belongs to the FACE — every avatar declares its own proportions, and
+ * a default stated as "94 wide" would silently mean something different for a
+ * face that is not 100 units across.
+ *
+ * 100% is the default rather than an extreme, so the 50–200% range gives room
+ * in both directions. She was previously drawn at twice this, which is what
+ * 200% now restores.
+ */
+export const BASE_UNIT_SCALE = 0.94;
+/**
+ * How far into a canvas the character stands, by default.
+ *
+ * A DEFAULT the host is expected to replace. The number came from one
+ * application's window and means nothing here; it survives only as the fallback
+ * for a caller that never says where the ground is. Anything with its own
+ * layout should call `setFeet` and ignore it.
+ *
+ * Why the stance is settable at all rather than fixed: a host may not be free
+ * to place its window where it likes. macOS pins a window's top edge to the
+ * work area, so a fixed standing height meant the character could never be
+ * carried close to the top of the display — dragged upward, she stopped dead in
+ * mid-air. Letting the host move the stance instead is what fixed that, and it
+ * is the general case, not a macOS special case.
+ */
+export const FEET_FROM_TOP = 340;
+/**
+ * Where she stands inside a canvas of a given height.
+ *
+ * ONE rule, called by the rig that draws her and by the code that anchors the
+ * bubble to her. They used to compute it separately — one as a fraction of the
+ * canvas and one as an offset from its bottom — which agree only when the
+ * canvas happens to be exactly her layout's height.
+ */
+export function feetY(cssHeight, clearance, feetFromTop = FEET_FROM_TOP) {
+    // Clamped, so a canvas smaller than the standing height still rests her on
+    // something rather than dropping her through the floor. The tuner sizes its
+    // own cells and is the caller that hits this.
+    //
+    // `clearance` is in PIXELS and therefore scaled — `BREATHING_UNITS` is in her
+    // design units, and passing it raw put her 4px low at 50% and 4px high at
+    // 150%, which is the whole distance between resting on the ground and
+    // hovering over it.
+    return Math.min(feetFromTop, cssHeight - clearance);
+}
+/**
+ * What the size setting accepts, as a percentage of `BASE_UNIT_SCALE`.
+ *
+ * DERIVED from `FACE_BOUNDS.size`, which is where a user-supplied value is
+ * refused. That table's own comment states the rule — "One table, read by BOTH
+ * the validator and the tuner's sliders. Two copies would let the editor offer
+ * a value the loader rejects" — and there had come to be four copies of these
+ * three numbers: here, in `persona-change.ts` as `SIZE_BAND`, and in the
+ * shelf's size control as `BAND`.
+ *
+ * The `fallback` is genuinely this module's own: `FACE_BOUNDS` says what is
+ * PERMITTED, and what to do with a value that is not a number at all is a
+ * question only `clampSizePercent` asks.
+ */
+export const SIZE_PERCENT = { ...FACE_BOUNDS.size, fallback: 100 };
+/**
+ * The widest and tallest she can ever be drawn, in design units.
+ *
+ * Deliberately conservative on the lean: the shear displaces the apex, where
+ * the body is narrowest, so adding it to the full width over-estimates. A
+ * window a few pixels too large is invisible; one a few pixels too small
+ * crops her, and that is the failure this whole calculation exists to prevent.
+ */
+export function worstCaseUnits(face) {
+    const width = face.bodyW * (1 + SQUASH_LIMIT);
+    return {
+        width: width + width * LEAN_LIMIT * SHEAR_GAIN,
+        height: face.bodyH / (1 - SQUASH_LIMIT),
+    };
+}
+/** Clamp a stored percentage to something renderable. */
+export function clampSizePercent(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return SIZE_PERCENT.fallback;
+    return Math.min(SIZE_PERCENT.max, Math.max(SIZE_PERCENT.min, value));
+}
+/**
+ * Everything both processes need, from a face and a size.
+ *
+ * Rounded to whole pixels because a BrowserWindow cannot be 293.7 wide — and
+ * if main rounds while the renderer does not, her base drifts off the ground
+ * line by a fraction of a pixel and the two disagree about where she is.
+ */
+export function layoutFor(face, sizePercent) {
+    const scale = BASE_UNIT_SCALE * (clampSizePercent(sizePercent) / 100);
+    const worst = worstCaseUnits(face);
+    const width = Math.round((worst.width + BREATHING_UNITS * 2) * scale);
+    const height = Math.round((worst.height + BREATHING_UNITS * 2) * scale);
+    return {
+        scale,
+        width,
+        height,
+        // Her base sits one clearance up from the bottom edge.
+        ground: (height - BREATHING_UNITS * scale) / height,
+        bodyWidth: face.bodyW * scale,
+        bodyHeight: face.bodyH * scale,
+    };
+}
+/**
+ * The largest scale whose WORST CASE still fits a canvas somebody else sized.
+ *
+ * For the tuner, which lays out its own grid of cells and cannot be told what
+ * size to be. The app never uses this — it sizes the window from `layoutFor`,
+ * which is the whole point of the inversion.
+ */
+export function fitToCanvas(face, cssWidth, cssHeight) {
+    // A canvas has to be a positive finite size to be fitted into. It used to
+    // take whatever it was given, and every bad answer flowed downstream in a
+    // shape nothing tested for: zero produced scale 0, which makes the renderer's
+    // ground calculation `0 / 0`, so she was positioned at NaN and vanished with
+    // no error; a negative width produced a negative scale, which mirrors her.
+    //
+    // A zero-sized canvas is not exotic -- an element that is display:none, or
+    // measured a frame before layout, reports exactly that.
+    if (!isPositive(cssWidth) || !isPositive(cssHeight))
+        return 0;
+    const worst = worstCaseUnits(face);
+    return Math.min(cssWidth / (worst.width + BREATHING_UNITS * 2), cssHeight / (worst.height + BREATHING_UNITS * 2));
+}
+function isPositive(value) {
+    return Number.isFinite(value) && value > 0;
+}
+//# sourceMappingURL=layout.js.map

package/dist/core/layout.js.map

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

package/dist/core/lens.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The lens: the region between an upper edge and a lower edge.
+ *
+ * One primitive for both the eyes and the mouth, and that unification is the
+ * design rather than a saving. Because both edges are independently signed, a
+ * single shape covers every state the face needs:
+ *
+ *   upper +, lower +   a dot, or an open mouth
+ *   upper ~0, lower ~0 a closed sliver -- a blink
+ *   upper +, lower -   a crescent -- the ^ ^ happy eye
+ *   upper -, lower +   a frown
+ *
+ * A NEGATIVE lower is the trick worth naming: it curves the bottom edge upward
+ * past the baseline, which is what turns an eye into a smile without a second
+ * asset and without a special case. Lip-sync and expression therefore drive one
+ * code path, so a mouth cannot be open according to one and shut according to
+ * the other.
+ *
+ * Each edge is half a SUPERELLIPSE, not a quadratic. The first version used
+ * quadratics and every eye came out a pointed almond, because two quadratics
+ * meeting at the corners always meet at an angle -- there is no value of the
+ * parameters that produces a round dot. A superellipse at `roundness` 2 is an
+ * ellipse, so the two halves join with a shared vertical tangent and the corner
+ * disappears; below 2 it sharpens toward a leaf, above 2 it squares off.
+ *
+ * Local space, origin at the lens centre, +y UP -- the same convention as
+ * geometry.ts.
+ */
+import type { Point } from './geometry.js';
+export interface LensShape {
+    readonly halfWidth: number;
+    /** How far the top edge bulges above the baseline. Negative dips it below. */
+    readonly upper: number;
+    /** How far the bottom edge dips below the baseline. Negative lifts it above. */
+    readonly lower: number;
+    /** Radians. Mirror it per side so both inner corners move the same way. */
+    readonly tilt: number;
+    /** Superellipse exponent. 2 is an ellipse; below sharpens, above squares off. */
+    readonly roundness: number;
+}
+export declare function lensOutline(lens: LensShape, steps?: number): Point[];
+/**
+ * Peak vertical extent, used to offset gaze so the pupil moves within the eye
+ * rather than by a fraction of nothing when the lid is nearly shut.
+ */
+export declare function lensHeight(lens: LensShape): number;
+//# sourceMappingURL=lens.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lens.d.ts","sourceRoot":"","sources":["../../src/core/lens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAE1C,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,gFAAgF;IAChF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,iFAAiF;IACjF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAMD,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,SAAK,GAAG,KAAK,EAAE,CA4BhE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAElD"}

package/dist/core/lens.js

@@ -0,0 +1,67 @@
+/**
+ * The lens: the region between an upper edge and a lower edge.
+ *
+ * One primitive for both the eyes and the mouth, and that unification is the
+ * design rather than a saving. Because both edges are independently signed, a
+ * single shape covers every state the face needs:
+ *
+ *   upper +, lower +   a dot, or an open mouth
+ *   upper ~0, lower ~0 a closed sliver -- a blink
+ *   upper +, lower -   a crescent -- the ^ ^ happy eye
+ *   upper -, lower +   a frown
+ *
+ * A NEGATIVE lower is the trick worth naming: it curves the bottom edge upward
+ * past the baseline, which is what turns an eye into a smile without a second
+ * asset and without a special case. Lip-sync and expression therefore drive one
+ * code path, so a mouth cannot be open according to one and shut according to
+ * the other.
+ *
+ * Each edge is half a SUPERELLIPSE, not a quadratic. The first version used
+ * quadratics and every eye came out a pointed almond, because two quadratics
+ * meeting at the corners always meet at an angle -- there is no value of the
+ * parameters that produces a round dot. A superellipse at `roundness` 2 is an
+ * ellipse, so the two halves join with a shared vertical tangent and the corner
+ * disappears; below 2 it sharpens toward a leaf, above 2 it squares off.
+ *
+ * Local space, origin at the lens centre, +y UP -- the same convention as
+ * geometry.ts.
+ */
+function rotate(x, y, sin, cos) {
+    return { x: x * cos - y * sin, y: x * sin + y * cos };
+}
+export function lensOutline(lens, steps = 28) {
+    const hw = Math.max(0, lens.halfWidth);
+    const k = Math.max(0.5, lens.roundness);
+    const power = 2 / k;
+    const sin = Math.sin(lens.tilt);
+    const cos = Math.cos(lens.tilt);
+    const points = [];
+    // Right, over the top, to left; then left, under the bottom, back to right.
+    // Parametrised by angle rather than by x so the samples stay evenly spread
+    // around the curve instead of bunching at the ends.
+    const half = (extent, from, to) => {
+        for (let i = 0; i <= steps; i++) {
+            const t = from + (to - from) * (i / steps);
+            const c = Math.cos(t);
+            const s = Math.sin(t);
+            const x = hw * Math.sign(c) * Math.pow(Math.abs(c), power);
+            const y = extent * Math.sign(s) * Math.pow(Math.abs(s), power);
+            points.push(rotate(x, y, sin, cos));
+        }
+    };
+    // Over the top with `upper`, then under the bottom with `lower`. On the lower
+    // sweep sin(t) is negative, so the formula already flips the sign -- passing
+    // `lower` unnegated is what makes a POSITIVE lower dip below the baseline and
+    // a negative one bow above it.
+    half(lens.upper, 0, Math.PI);
+    half(lens.lower, Math.PI, Math.PI * 2);
+    return points;
+}
+/**
+ * Peak vertical extent, used to offset gaze so the pupil moves within the eye
+ * rather than by a fraction of nothing when the lid is nearly shut.
+ */
+export function lensHeight(lens) {
+    return Math.max(Math.abs(lens.upper), Math.abs(lens.lower));
+}
+//# sourceMappingURL=lens.js.map

package/dist/core/lens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lens.js","sourceRoot":"","sources":["../../src/core/lens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAgBH,SAAS,MAAM,CAAC,CAAS,EAAE,CAAS,EAAE,GAAW,EAAE,GAAW;IAC5D,OAAO,EAAE,CAAC,EAAE,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,EAAE,CAAA;AACvD,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAe,EAAE,KAAK,GAAG,EAAE;IACrD,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,CAAA;IACtC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,CAAA;IACvC,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,CAAA;IACnB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC/B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAE/B,MAAM,MAAM,GAAY,EAAE,CAAA;IAC1B,4EAA4E;IAC5E,2EAA2E;IAC3E,oDAAoD;IACpD,MAAM,IAAI,GAAG,CAAC,MAAc,EAAE,IAAY,EAAE,EAAU,EAAQ,EAAE;QAC9D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;YAChC,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,CAAA;YAC1C,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;YACrB,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;YACrB,MAAM,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAA;YAC1D,MAAM,CAAC,GAAG,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAA;YAC9D,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAA;QACrC,CAAC;IACH,CAAC,CAAA;IACD,8EAA8E;IAC9E,6EAA6E;IAC7E,8EAA8E;IAC9E,+BAA+B;IAC/B,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,CAAC,CAAA;IAC5B,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC,CAAA;IACtC,OAAO,MAAM,CAAA;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,IAAe;IACxC,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAA;AAC7D,CAAC"}

package/dist/core/looks.d.ts

@@ -0,0 +1,77 @@
+/**
+ * How each emotion deforms the neutral face.
+ *
+ * Every Emotion gets an entry, enforced by `Record<Emotion, Look>`. Letting one
+ * fall through to neutral would make `caps.presetExpressions` a lie: the
+ * backend would claim to support an expression it renders identically to no
+ * expression at all, and the caller has no way to discover that.
+ *
+ * Values are multipliers on the tuned base geometry rather than absolute sizes,
+ * so retuning the face in the tuner does not invalidate the table.
+ */
+import { type Emotion } from './vocabulary.js';
+export interface Look {
+    /** Multiplies the eye's upper arc. */
+    readonly eyeUpper: number;
+    /** Multiplies the eye's lower arc. NEGATIVE turns the eye into a crescent -- see lens.ts. */
+    readonly eyeLower: number;
+    readonly eyeWidth: number;
+    /** Radians, mirrored per side. Positive brings the inner corners down. */
+    readonly eyeTilt: number;
+    readonly mouthUpper: number;
+    readonly mouthLower: number;
+    readonly mouthWidth: number;
+    /**
+     * 0..1 opacity of the mouth. 0 removes it entirely.
+     *
+     * Only `sleepy` uses it, and only for the resting pose: a sleeping mochi is a
+     * shape with two closed eyes, and a mouth left on it reads as awake-but-quiet
+     * rather than asleep.
+     *
+     * This does NOT weaken the layering rule, which says no layer above the
+     * mouth may overwrite it, because a gesture holding her jaw shut while audio
+     * is playing reads as broken. `paintMouth` therefore takes the LOUDER of this
+     * and whatever is actually driving the mouth -- so anything making a sound
+     * wins, and the expression can only hide a mouth that is already still.
+     */
+    readonly mouthAlpha: number;
+    /** 0..1 extra cheek colour, on top of the resting amount. */
+    readonly cheek: number;
+    /**
+     * 0..1 opacity of the catchlight -- the "her eyes lit up" block.
+     *
+     * A property of the EMOTION rather than a timer, which is what makes "her
+     * eyes lit up" mean something: it appears when she is delighted or startled
+     * and is absent the rest of the time, so seeing it carries information. A
+     * highlight that were simply always on would be a shading detail, and one
+     * that blinked on a schedule would be noise.
+     *
+     * It blends with intensity like everything else here, so the waking perk --
+     * `surprised` at 0.6 for 1.4 seconds, in `face.ts` -- shows a partial glint
+     * rather than a full one.
+     *
+     * **It does not fade.** This entry used to say it did, and it was wrong
+     * twice over: nothing set the perk at all, and only `squash` runs through a
+     * spring -- every other channel of a `Look` is applied on the frame it is
+     * set. A hold ENDS an expression; it does not ease it out. Anyone wanting a
+     * fade has to interpolate the look itself, which is a change to this whole
+     * pipeline rather than a value in this table.
+     */
+    readonly sparkle: number;
+    /** -1..1 gaze bias, added to whatever the cursor is doing. Thinking looks up and away. */
+    readonly gazeX: number;
+    readonly gazeY: number;
+    /** Postural squash. Surprise stretches her up; sleepy lets her spread. */
+    readonly squash: number;
+    readonly lean: number;
+}
+export declare const NEUTRAL: Look;
+export declare const LOOKS: Readonly<Record<Emotion, Look>>;
+/**
+ * Neutral blended toward the named emotion by intensity.
+ *
+ * Intensity 0 is exactly neutral for every emotion, which is what lets a signal
+ * decay smoothly rather than snapping when it expires.
+ */
+export declare function blendLook(emotion: Emotion, intensity: number): Look;
+//# sourceMappingURL=looks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"looks.d.ts","sourceRoot":"","sources":["../../src/core/looks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAW,KAAK,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAEvD,MAAM,WAAW,IAAI;IACnB,sCAAsC;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,6FAA6F;IAC7F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,0FAA0F;IAC1F,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED,eAAO,MAAM,OAAO,EAAE,IAerB,CAAA;AAED,eAAO,MAAM,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,CAsHjD,CAAA;AAID;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAWnE"}