@ai-presence/face 0.1.0

package/README.md

@@ -0,0 +1,162 @@
+# @ai-presence/face
+
+Reference face renderer primitives for AI Presence Kit.
+
+This package maps canonical presence snapshots from `@ai-presence/core` to renderer-specific face controls. The expression mapper remains available, and the additive controller APIs turn the same interaction-posture snapshot into parallel micro-decisions and deterministic per-frame micro-movement for gaze, blink, brows, mouth, posture, and motion.
+
+```js
+import { faceExpressionForPresence } from "@ai-presence/face";
+
+const expression = faceExpressionForPresence(snapshot);
+```
+
+```js
+import { faceControllerDecisionsForPresence, faceControlsForPresence } from "@ai-presence/face";
+
+const controls = faceControlsForPresence(snapshot, { trace });
+const report = faceControllerDecisionsForPresence(snapshot, { trace });
+
+renderer.setGaze(controls.gaze);
+renderer.setMouth(controls.mouth);
+
+console.log(report.decisions.gaze.controller); // "gaze-controller"
+```
+
+```js
+import {
+  faceControllerCoherenceForFrame,
+  faceControllerDecisionTraceForFrame,
+  faceControllerFrameForPresence,
+} from "@ai-presence/face";
+
+const frameReport = faceControllerFrameForPresence(snapshot, {
+  trace,
+  timeMs: performance.now(),
+  motionScale: matchMedia("(prefers-reduced-motion: reduce)").matches ? 0 : 1,
+});
+const decisionTrace = faceControllerDecisionTraceForFrame(frameReport);
+
+renderer.setGaze(frameReport.frame.gaze);
+renderer.setBlink(frameReport.frame.blink);
+renderer.setPosture(frameReport.frame.posture);
+
+console.log(frameReport.coherence.rendererSafe); // true
+console.log(faceControllerCoherenceForFrame(frameReport).channels); // ["gaze", "blink", "brows", "mouth", "posture", "motion"]
+console.log(decisionTrace.decisions.gaze.control.target); // "response-origin"
+console.log(decisionTrace.transitionContext);
+// { previousState: "ready", transitionEvent: "submit", transitionAgeMs: 80 }
+```
+
+```js
+import { renderPresenceFaceSvg } from "@ai-presence/face";
+
+const result = renderPresenceFaceSvg(snapshot, {
+  trace,
+  timeMs: performance.now(),
+  motionScale: 0,
+});
+
+container.innerHTML = result.svg;
+console.log(result.channelEvidence.mouth.frame.shape);
+console.log(result.attributes.motionScale); // "0"
+console.log(result.decisionTrace.decisionCount); // 6
+console.log(result.attributes.decisionTrace); // "complete"
+```
+
+The controller does not claim hidden internal state. It stays grounded in observable states such as `reading`, `thinking`, `waiting`, `streaming`, `speaking`, `interrupted`, and `ready`, then lets each facial subsystem make a small local decision from the shared snapshot and optional trace/history.
+
+`faceControlsForPresence` remains the renderer-friendly compatibility surface. `faceControllerDecisionsForPresence` exposes the same composition as an inspection report:
+
+```js
+{
+  state: "waiting",
+  expression: "listening",
+  sharedInputs: {
+    state: "waiting",
+    attentionTarget: "response",
+    latencyPhase: "before-output"
+  },
+  decisions: {
+    gaze: { channel: "gaze", controller: "gaze-controller", reads: ["state", "attentionTarget", "transitionEvent", "..."], control: {} },
+    blink: { channel: "blink", controller: "blink-controller", reads: ["state", "..."], control: {} },
+    brows: { channel: "brows", controller: "brows-controller", reads: ["state", "transitionEvent", "transitionAgeMs", "..."], control: {} },
+    mouth: { channel: "mouth", controller: "mouth-controller", reads: ["state", "speechActivity", "transitionEvent", "..."], control: {} },
+    posture: { channel: "posture", controller: "posture-controller", reads: ["state", "energy", "transitionEvent", "..."], control: {} },
+    motion: { channel: "motion", controller: "motion-controller", reads: ["state", "anticipation", "..."], control: {} }
+  }
+}
+```
+
+`faceControllerFrameForPresence` returns the same report fields plus a frozen `frame` object and frozen `coherence` audit. The frame keeps controller decisions stable and adds bounded temporal values such as blink `phase`, mouth `beat`, posture `breath`, and motion offsets so renderers can animate interaction posture without adding their own timing policy.
+
+`faceControllerDecisionTraceForFrame(frameReport)` turns a frame report into bounded per-channel controller evidence. It keeps all six channels inspectable as local decisions before the composed frame is consumed by a renderer:
+
+```js
+{
+  channels: ["gaze", "blink", "brows", "mouth", "posture", "motion"],
+  transitionContext: {
+    previousState: "ready",
+    transitionEvent: "submit",
+    transitionAgeMs: 80
+  },
+  decisionCount: 6,
+  complete: true,
+  rendererSafe: true,
+  warningCount: 0,
+  decisions: {
+    gaze: {
+      channel: "gaze",
+      controller: "gaze-controller",
+      reads: ["state", "detail.question", "attentionTarget", "transitionEvent", "..."],
+      control: { target: "response-origin", x: -0.08, y: -0.04, focus: 0.66 },
+      frame: { target: "response-origin", x: -0.079, y: -0.044, focus: 0.66, driftX: 0.007, driftY: -0.032 },
+      present: true,
+      bounded: true,
+      rendererSafe: true,
+      warningCount: 0,
+      warnings: []
+    }
+  }
+}
+```
+
+Use the decision trace for debug UIs, tests, logs, and adapter smoke output that need to show which controller read which runtime fields without parsing full internal control objects or core trace history. `transitionContext` is renderer-owned evidence that a fresh `submit`, `stream-open`, `token`, or `interrupt` cue was available to micro-controllers such as gaze, blink, brows, mouth, posture, and motion. It is evidence for observable interaction posture, not a claim about hidden user or model state.
+
+The coherence audit proves the six independently decided channels compose into one renderer-consumable frame:
+
+```js
+{
+  channels: ["gaze", "blink", "brows", "mouth", "posture", "motion"],
+  complete: true,
+  bounded: true,
+  rendererSafe: true,
+  summary: {
+    channelCount: 6,
+    presentChannelCount: 6,
+    boundedChannelCount: 6,
+    gazeTarget: "response-origin",
+    gazeFocus: 0.66,
+    blinkOpenness: 0.9,
+    mouthShape: "preparing",
+    mouthActivity: 0.16,
+    postureLean: 0.24,
+    motionEnergy: 0.46,
+    motionRecovery: 0
+  },
+  channelReports: {
+    gaze: { channel: "gaze", present: true, bounded: true, summary: {}, warnings: [] },
+    blink: { channel: "blink", present: true, bounded: true, summary: {}, warnings: [] },
+    brows: { channel: "brows", present: true, bounded: true, summary: {}, warnings: [] },
+    mouth: { channel: "mouth", present: true, bounded: true, summary: {}, warnings: [] },
+    posture: { channel: "posture", present: true, bounded: true, summary: {}, warnings: [] },
+    motion: { channel: "motion", present: true, bounded: true, summary: {}, warnings: [] }
+  },
+  warnings: []
+}
+```
+
+Use `faceControllerCoherenceForFrame(frameReport)` when auditing a saved or externally assembled report. Missing channels, mismatched controller metadata, invalid targets/shapes, and out-of-range numeric values make `rendererSafe` false and appear in `warnings`.
+
+Pass `motionScale` when a downstream renderer needs reduced motion. `motionScale: 1` is the default live temporal behavior, `motionScale: 0` produces deterministic still frames across different `timeMs` values for the same snapshot/options, and values between `0` and `1` reduce temporal blink closure, drift, mouth beat, breath, anticipation/recovery kicks, motion transition offsets, and continuous motion offsets. The gaze, brows, mouth, and posture transition responses are static controller decisions from `transitionEvent` and `transitionAgeMs`; they do not read frame time, so reduced-motion frames remain deterministic while still exposing the current interaction-posture cue. The option does not remove the six controller channels or their evidence; gaze target, blink baseline, brows, mouth shape, posture, and motion decisions remain available for custom renderers.
+
+`renderPresenceFaceSvg` is the no-DOM reference SVG surface. It calls `faceControllerFrameForPresence`, derives `faceControllerDecisionTraceForFrame` from that same frame report, returns a compact SVG string, and includes state, expression, frame data, six-channel evidence, and renderer-owned decision-trace evidence so downstream AI interfaces can inspect what drove the rendered posture without copying the browser demo internals. The SVG root mirrors the compact proof as `data-face-decision-trace*` attributes, includes `data-face-latency-phase` when shared control inputs provide it, and mirrors fresh transition evidence through `data-face-previous-state`, `data-face-transition-event`, and `data-face-transition-age-ms`.

package/dist/index.mjs

@@ -0,0 +1,21 @@
+import face from "../src/presence-face.js";
+
+export const FaceExpression = face.FaceExpression;
+export const FACE_EXPRESSIONS = face.FACE_EXPRESSIONS;
+export const DEFAULT_FACE_CONTROL_PROFILE = face.DEFAULT_FACE_CONTROL_PROFILE;
+export const DEFAULT_FACE_MAP = face.DEFAULT_FACE_MAP;
+export const FACE_CONTROL_CHANNELS = face.FACE_CONTROL_CHANNELS;
+export const createFaceControllerFrameRuntime = face.createFaceControllerFrameRuntime;
+export const createFaceControllerRuntime = face.createFaceControllerRuntime;
+export const createFaceRenderer = face.createFaceRenderer;
+export const renderPresenceFaceSvg = face.renderPresenceFaceSvg;
+export const faceControllerCoherenceForFrame = face.faceControllerCoherenceForFrame;
+export const faceControllerDecisionTraceForFrame = face.faceControllerDecisionTraceForFrame;
+export const faceControllerFrameForPresence = face.faceControllerFrameForPresence;
+export const faceControllerDecisionsForPresence = face.faceControllerDecisionsForPresence;
+export const faceControlsForPresence = face.faceControlsForPresence;
+export const faceExpressionForPresence = face.faceExpressionForPresence;
+export const isFaceExpression = face.isFaceExpression;
+export const normalizeFaceExpression = face.normalizeFaceExpression;
+
+export default face;

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@ai-presence/face",
+  "version": "0.1.0",
+  "description": "SVG reference face renderer with parallel presence controllers.",
+  "type": "commonjs",
+  "main": "./src/presence-face.js",
+  "module": "./dist/index.mjs",
+  "types": "./src/presence-face.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/presence-face.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./src/presence-face.js",
+      "default": "./src/presence-face.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "@ai-presence/core": "0.1.0"
+  },
+  "sideEffects": false,
+  "license": "MIT"
+}

package/src/presence-face.d.ts

@@ -0,0 +1,346 @@
+import type {
+  PresenceControlInputs,
+  PresenceLatencyPhase,
+  PresenceSnapshot,
+  PresenceStateValue,
+  PresenceTransitionEvent,
+} from "@ai-presence/core";
+
+export declare const FaceExpression: Readonly<{
+  IDLE: "idle";
+  LISTENING: "listening";
+  READING: "reading";
+  THINKING: "thinking";
+  CURIOUS: "curious";
+  AMUSED: "amused";
+  DELIGHTED: "delighted";
+  UNCERTAIN: "uncertain";
+  CONCERNED: "concerned";
+  READY: "ready";
+  SPEAKING: "speaking";
+}>;
+
+export type FaceExpressionValue = typeof FaceExpression[keyof typeof FaceExpression];
+
+export interface FaceControlProfile {
+  blinkCadenceMs?: number;
+  drift?: number;
+  settleMs?: number;
+}
+
+export interface FaceControlOptions extends FaceRendererOptions {
+  detail?: Record<string, unknown>;
+  history?: ReadonlyArray<Partial<PresenceSnapshot> & Record<string, unknown>>;
+  /**
+   * Scales temporal micro-motion in generated frames and SVG output.
+   * Use 1 for live motion, 0 for deterministic still/reduced-motion output.
+   * Values outside 0..1 are clamped.
+   */
+  motionScale?: number;
+  now?: number | (() => number);
+  profile?: FaceControlProfile;
+  timeMs?: number | (() => number);
+  trace?: ReadonlyArray<Partial<PresenceSnapshot> & Record<string, unknown>> | {
+    getEntries(): ReadonlyArray<Partial<PresenceSnapshot> & Record<string, unknown>>;
+  };
+}
+
+export interface FaceGazeControl {
+  target: "audience" | "content" | "input" | "middle-distance" | "question" | "response-origin" | "status" | "user";
+  x: number;
+  y: number;
+  focus: number;
+}
+
+export interface FaceBlinkControl {
+  openness: number;
+  cadenceMs: number;
+  pulse: boolean;
+}
+
+export interface FaceBrowsControl {
+  lift: number;
+  pinch: number;
+  asymmetry: number;
+}
+
+export interface FaceMouthControl {
+  shape: "curious" | "downturned" | "held" | "listening" | "preparing" | "pressed" | "release" | "rest" | "soft-smile" | "speaking";
+  openness: number;
+  activity: number;
+  tension: number;
+}
+
+export interface FacePostureControl {
+  lean: number;
+  turn: number;
+  energy: number;
+  recovery: number;
+}
+
+export interface FaceMotionControl {
+  energy: number;
+  drift: number;
+  anticipation: number;
+  recovery: number;
+  settleMs: number;
+}
+
+export interface FaceGazeFrame extends FaceGazeControl {
+  driftX: number;
+  driftY: number;
+}
+
+export interface FaceBlinkFrame extends FaceBlinkControl {
+  phase: number;
+}
+
+export interface FaceBrowsFrame extends FaceBrowsControl {}
+
+export interface FaceMouthFrame extends FaceMouthControl {
+  beat: number;
+}
+
+export interface FacePostureFrame extends FacePostureControl {
+  breath: number;
+}
+
+export interface FaceMotionFrame extends FaceMotionControl {
+  offsetX: number;
+  offsetY: number;
+}
+
+export interface FaceControllerFrame {
+  gaze: FaceGazeFrame;
+  blink: FaceBlinkFrame;
+  brows: FaceBrowsFrame;
+  mouth: FaceMouthFrame;
+  posture: FacePostureFrame;
+  motion: FaceMotionFrame;
+}
+
+export type FaceControlChannel = "gaze" | "blink" | "brows" | "mouth" | "posture" | "motion";
+
+export interface FaceControllerChannelCoherence {
+  channel: FaceControlChannel;
+  present: boolean;
+  bounded: boolean;
+  summary: Readonly<Record<string, string | number | boolean | null>>;
+  warnings: readonly string[];
+}
+
+export interface FaceControllerCoherence {
+  channels: readonly FaceControlChannel[];
+  complete: boolean;
+  bounded: boolean;
+  rendererSafe: boolean;
+  summary: Readonly<{
+    channelCount: number;
+    presentChannelCount: number;
+    boundedChannelCount: number;
+    gazeTarget: FaceGazeFrame["target"] | null;
+    gazeFocus: number | null;
+    blinkOpenness: number | null;
+    mouthShape: FaceMouthFrame["shape"] | null;
+    mouthActivity: number | null;
+    postureLean: number | null;
+    motionEnergy: number | null;
+    motionRecovery: number | null;
+  }>;
+  channelReports: Readonly<Record<FaceControlChannel, FaceControllerChannelCoherence>>;
+  warnings: readonly string[];
+}
+
+export type FaceControllerDecisionTraceSummaryValue = string | number | boolean | null;
+
+export interface FaceControllerTransitionContext {
+  previousState: PresenceStateValue | null;
+  transitionEvent: PresenceTransitionEvent | null;
+  transitionAgeMs: number | null;
+}
+
+export interface FaceControllerDecisionTraceChannel {
+  channel: FaceControlChannel;
+  controller: string | null;
+  reads: readonly string[];
+  control: Readonly<Record<string, FaceControllerDecisionTraceSummaryValue>>;
+  frame: Readonly<Record<string, FaceControllerDecisionTraceSummaryValue>>;
+  present: boolean;
+  bounded: boolean;
+  rendererSafe: boolean;
+  warningCount: number;
+  warnings: readonly string[];
+}
+
+export interface FaceControllerDecisionTrace {
+  channels: readonly FaceControlChannel[];
+  transitionContext: FaceControllerTransitionContext;
+  decisionCount: number;
+  complete: boolean;
+  rendererSafe: boolean;
+  warningCount: number;
+  warnings: readonly string[];
+  decisions: Readonly<Record<FaceControlChannel, FaceControllerDecisionTraceChannel>>;
+}
+
+export interface FaceControllerDecision<TControl> {
+  channel: FaceControlChannel;
+  controller: string;
+  reads: readonly string[];
+  control: TControl;
+}
+
+export interface FaceControllerDecisions {
+  gaze: FaceControllerDecision<FaceGazeControl>;
+  blink: FaceControllerDecision<FaceBlinkControl>;
+  brows: FaceControllerDecision<FaceBrowsControl>;
+  mouth: FaceControllerDecision<FaceMouthControl>;
+  posture: FaceControllerDecision<FacePostureControl>;
+  motion: FaceControllerDecision<FaceMotionControl>;
+}
+
+export interface FaceControllerDecisionReport {
+  state: PresenceStateValue;
+  expression: FaceExpressionValue;
+  sharedInputs: PresenceControlInputs | null;
+  decisions: FaceControllerDecisions;
+}
+
+export interface FaceControllerFrameReport extends FaceControllerDecisionReport {
+  frame: FaceControllerFrame;
+  coherence: FaceControllerCoherence;
+}
+
+export interface PresenceFaceSvgOptions extends FaceControlOptions {
+  className?: string;
+  height?: number;
+  title?: string;
+  width?: number;
+}
+
+export interface PresenceFaceSvgChannelEvidence<TFrame> {
+  controller: string;
+  reads: readonly string[];
+  frame: TFrame;
+}
+
+export interface PresenceFaceSvgChannelEvidenceMap {
+  gaze: PresenceFaceSvgChannelEvidence<FaceGazeFrame>;
+  blink: PresenceFaceSvgChannelEvidence<FaceBlinkFrame>;
+  brows: PresenceFaceSvgChannelEvidence<FaceBrowsFrame>;
+  mouth: PresenceFaceSvgChannelEvidence<FaceMouthFrame>;
+  posture: PresenceFaceSvgChannelEvidence<FacePostureFrame>;
+  motion: PresenceFaceSvgChannelEvidence<FaceMotionFrame>;
+}
+
+export interface PresenceFaceSvgAttributes {
+  state: PresenceStateValue;
+  expression: FaceExpressionValue;
+  channels: string;
+  gazeTarget: FaceGazeFrame["target"];
+  blinkOpenness: string;
+  browsPinch: string;
+  mouthShape: FaceMouthFrame["shape"];
+  postureLean: string;
+  motionEnergy: string;
+  motionScale: string;
+  decisionTrace: "complete" | "incomplete";
+  decisionTraceChannels: string;
+  decisionTraceDecisions: string;
+  decisionTraceWarnings: string;
+  decisionTraceRendererSafe: "true" | "false";
+  latencyPhase?: PresenceLatencyPhase;
+  previousState?: PresenceStateValue;
+  transitionEvent?: PresenceTransitionEvent;
+  transitionAgeMs?: string;
+}
+
+export interface PresenceFaceSvgRenderResult {
+  svg: string;
+  state: PresenceStateValue;
+  expression: FaceExpressionValue;
+  frame: FaceControllerFrame;
+  frameReport: FaceControllerFrameReport;
+  attributes: PresenceFaceSvgAttributes;
+  channelEvidence: PresenceFaceSvgChannelEvidenceMap;
+  decisionTrace: FaceControllerDecisionTrace;
+}
+
+export interface FaceControls {
+  expression: FaceExpressionValue;
+  gaze: FaceGazeControl;
+  blink: FaceBlinkControl;
+  brows: FaceBrowsControl;
+  mouth: FaceMouthControl;
+  posture: FacePostureControl;
+  motion: FaceMotionControl;
+}
+
+export interface FaceControllerRuntime {
+  getControls(): FaceControls | null;
+  update(snapshot: PresenceSnapshot | PresenceStateValue, options?: FaceControlOptions & {
+    update?: (controls: FaceControls, snapshot: PresenceSnapshot | PresenceStateValue) => void;
+  }): FaceControls;
+}
+
+export interface FaceControllerFrameRuntime {
+  getFrame(): FaceControllerFrameReport | null;
+  update(snapshot: PresenceSnapshot | PresenceStateValue, options?: FaceControlOptions & {
+    update?: (frame: FaceControllerFrameReport, snapshot: PresenceSnapshot | PresenceStateValue) => void;
+  }): FaceControllerFrameReport;
+}
+
+export interface FaceRenderer {
+  getExpression(): FaceExpressionValue | null;
+  render(snapshot: PresenceSnapshot): FaceExpressionValue;
+}
+
+export interface FaceRendererOptions {
+  map?: Partial<Record<PresenceStateValue, FaceExpressionValue>>;
+  render?: (expression: FaceExpressionValue, snapshot: PresenceSnapshot) => void;
+}
+
+export declare const FACE_EXPRESSIONS: readonly FaceExpressionValue[];
+export declare const DEFAULT_FACE_CONTROL_PROFILE: Readonly<{
+  blinkCadenceMs: number;
+  drift: number;
+  settleMs: number;
+}>;
+export declare const FACE_CONTROL_CHANNELS: readonly FaceControlChannel[];
+export declare const DEFAULT_FACE_MAP: Readonly<Record<PresenceStateValue, FaceExpressionValue>>;
+
+export declare function createFaceControllerRuntime(options?: FaceControlOptions & {
+  update?: (controls: FaceControls, snapshot: PresenceSnapshot | PresenceStateValue) => void;
+}): FaceControllerRuntime;
+export declare function createFaceControllerFrameRuntime(options?: FaceControlOptions & {
+  update?: (frame: FaceControllerFrameReport, snapshot: PresenceSnapshot | PresenceStateValue) => void;
+}): FaceControllerFrameRuntime;
+export declare function createFaceRenderer(options?: FaceRendererOptions): FaceRenderer;
+export declare function faceControllerDecisionsForPresence(
+  snapshotOrState: PresenceSnapshot | PresenceStateValue,
+  options?: FaceControlOptions,
+): FaceControllerDecisionReport;
+export declare function faceControllerCoherenceForFrame(
+  frameReport?: Partial<FaceControllerFrameReport> & Record<string, unknown>,
+): FaceControllerCoherence;
+export declare function faceControllerDecisionTraceForFrame(
+  frameReport?: Partial<FaceControllerFrameReport> & Record<string, unknown>,
+): FaceControllerDecisionTrace;
+export declare function faceControllerFrameForPresence(
+  snapshotOrState: PresenceSnapshot | PresenceStateValue,
+  options?: FaceControlOptions,
+): FaceControllerFrameReport;
+export declare function faceControlsForPresence(
+  snapshotOrState: PresenceSnapshot | PresenceStateValue,
+  options?: FaceControlOptions,
+): FaceControls;
+export declare function faceExpressionForPresence(
+  snapshotOrState: PresenceSnapshot | PresenceStateValue,
+  options?: FaceRendererOptions & { detail?: Record<string, unknown> },
+): FaceExpressionValue;
+export declare function isFaceExpression(value: unknown): value is FaceExpressionValue;
+export declare function normalizeFaceExpression(value: unknown, fallback?: FaceExpressionValue): FaceExpressionValue;
+export declare function renderPresenceFaceSvg(
+  snapshotOrState: PresenceSnapshot | PresenceStateValue,
+  options?: PresenceFaceSvgOptions,
+): PresenceFaceSvgRenderResult;