@femtomc/mu-core 26.2.99 → 26.2.101

package/README.md

@@ -34,6 +34,18 @@ await runContext({ runId: newRunId() }, async () => {
 console.log(await jsonl.read());
 ```
 
+## HUD contract helpers
+
+`@femtomc/mu-core` exports a versioned HUD contract, deterministic JSON helper, and shared runtime loop:
+
+- `HudDocSchema`, `HUD_CONTRACT_VERSION`
+- `parseHudDoc(...)`, `normalizeHudDocs(...)`
+- `serializeHudDocTextFallback(...)`, `serializeHudDocsTextFallback(...)`
+- `stableSerializeJson(...)`
+- `HudRuntime` + `HudProvider` for provider registration, reducer updates, ordered effect execution, and HUD snapshot emission
+
+These are runtime-agnostic primitives intended for shared HUD capture/render pipelines.
+
 ## Tests / Typecheck
 
 From the `mu/` repo root:

package/dist/hud.d.ts

@@ -0,0 +1,207 @@
+import { z } from "zod";
+export declare const HUD_CONTRACT_VERSION = 1;
+export declare const HudToneSchema: z.ZodEnum<{
+    error: "error";
+    info: "info";
+    success: "success";
+    warning: "warning";
+    muted: "muted";
+    accent: "accent";
+    dim: "dim";
+}>;
+export type HudTone = z.infer<typeof HudToneSchema>;
+export declare const HudActionKindSchema: z.ZodEnum<{
+    primary: "primary";
+    secondary: "secondary";
+    danger: "danger";
+}>;
+export type HudActionKind = z.infer<typeof HudActionKindSchema>;
+export declare const HudChipSchema: z.ZodObject<{
+    key: z.ZodString;
+    label: z.ZodString;
+    tone: z.ZodOptional<z.ZodEnum<{
+        error: "error";
+        info: "info";
+        success: "success";
+        warning: "warning";
+        muted: "muted";
+        accent: "accent";
+        dim: "dim";
+    }>>;
+}, z.core.$strict>;
+export type HudChip = z.infer<typeof HudChipSchema>;
+export declare const HudKvItemSchema: z.ZodObject<{
+    key: z.ZodString;
+    label: z.ZodString;
+    value: z.ZodString;
+    tone: z.ZodOptional<z.ZodEnum<{
+        error: "error";
+        info: "info";
+        success: "success";
+        warning: "warning";
+        muted: "muted";
+        accent: "accent";
+        dim: "dim";
+    }>>;
+}, z.core.$strict>;
+export type HudKvItem = z.infer<typeof HudKvItemSchema>;
+export declare const HudChecklistItemSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    done: z.ZodBoolean;
+}, z.core.$strict>;
+export type HudChecklistItem = z.infer<typeof HudChecklistItemSchema>;
+export declare const HudSectionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"kv">;
+    title: z.ZodOptional<z.ZodString>;
+    items: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        label: z.ZodString;
+        value: z.ZodString;
+        tone: z.ZodOptional<z.ZodEnum<{
+            error: "error";
+            info: "info";
+            success: "success";
+            warning: "warning";
+            muted: "muted";
+            accent: "accent";
+            dim: "dim";
+        }>>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"checklist">;
+    title: z.ZodOptional<z.ZodString>;
+    items: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        done: z.ZodBoolean;
+    }, z.core.$strict>>>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"activity">;
+    title: z.ZodOptional<z.ZodString>;
+    lines: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"text">;
+    title: z.ZodOptional<z.ZodString>;
+    text: z.ZodString;
+    tone: z.ZodOptional<z.ZodEnum<{
+        error: "error";
+        info: "info";
+        success: "success";
+        warning: "warning";
+        muted: "muted";
+        accent: "accent";
+        dim: "dim";
+    }>>;
+}, z.core.$strict>], "kind">;
+export type HudSection = z.infer<typeof HudSectionSchema>;
+export declare const HudActionSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    command_text: z.ZodString;
+    kind: z.ZodOptional<z.ZodEnum<{
+        primary: "primary";
+        secondary: "secondary";
+        danger: "danger";
+    }>>;
+}, z.core.$strict>;
+export type HudAction = z.infer<typeof HudActionSchema>;
+export declare const HudDocSchema: z.ZodObject<{
+    v: z.ZodDefault<z.ZodLiteral<1>>;
+    hud_id: z.ZodString;
+    title: z.ZodString;
+    scope: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    chips: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        label: z.ZodString;
+        tone: z.ZodOptional<z.ZodEnum<{
+            error: "error";
+            info: "info";
+            success: "success";
+            warning: "warning";
+            muted: "muted";
+            accent: "accent";
+            dim: "dim";
+        }>>;
+    }, z.core.$strict>>>;
+    sections: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"kv">;
+        title: z.ZodOptional<z.ZodString>;
+        items: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            label: z.ZodString;
+            value: z.ZodString;
+            tone: z.ZodOptional<z.ZodEnum<{
+                error: "error";
+                info: "info";
+                success: "success";
+                warning: "warning";
+                muted: "muted";
+                accent: "accent";
+                dim: "dim";
+            }>>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"checklist">;
+        title: z.ZodOptional<z.ZodString>;
+        items: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            done: z.ZodBoolean;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"activity">;
+        title: z.ZodOptional<z.ZodString>;
+        lines: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"text">;
+        title: z.ZodOptional<z.ZodString>;
+        text: z.ZodString;
+        tone: z.ZodOptional<z.ZodEnum<{
+            error: "error";
+            info: "info";
+            success: "success";
+            warning: "warning";
+            muted: "muted";
+            accent: "accent";
+            dim: "dim";
+        }>>;
+    }, z.core.$strict>], "kind">>>;
+    actions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        command_text: z.ZodString;
+        kind: z.ZodOptional<z.ZodEnum<{
+            primary: "primary";
+            secondary: "secondary";
+            danger: "danger";
+        }>>;
+    }, z.core.$strict>>>;
+    snapshot_compact: z.ZodString;
+    snapshot_multiline: z.ZodOptional<z.ZodString>;
+    updated_at_ms: z.ZodNumber;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+export type HudDoc = z.infer<typeof HudDocSchema>;
+export declare function stableSerializeJson(value: unknown, opts?: {
+    pretty?: boolean;
+}): string;
+export type HudTextFallbackMode = "compact" | "multiline";
+export declare function serializeHudDocTextFallback(input: unknown, opts?: {
+    mode?: HudTextFallbackMode;
+    maxChars?: number;
+    maxSectionItems?: number;
+    maxActions?: number;
+}): string;
+export declare function serializeHudDocsTextFallback(input: unknown, opts?: {
+    mode?: HudTextFallbackMode;
+    maxChars?: number;
+    maxDocs?: number;
+    maxSectionItems?: number;
+    maxActions?: number;
+}): string;
+export declare function parseHudDoc(input: unknown): HudDoc | null;
+export declare function normalizeHudDocs(input: unknown, opts?: {
+    maxDocs?: number;
+}): HudDoc[];
+//# sourceMappingURL=hud.d.ts.map

package/dist/hud.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hud.d.ts","sourceRoot":"","sources":["../src/hud.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAItC,eAAO,MAAM,aAAa;;;;;;;;EAA4E,CAAC;AACvG,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAEpD,eAAO,MAAM,mBAAmB;;;;EAA6C,CAAC;AAC9E,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,aAAa;;;;;;;;;;;;kBAMhB,CAAC;AACX,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAEpD,eAAO,MAAM,eAAe;;;;;;;;;;;;;kBAOlB,CAAC;AACX,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,eAAO,MAAM,sBAAsB;;;;kBAMzB,CAAC;AACX,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BA8B3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,eAAe;;;;;;;;;kBAOlB,CAAC;AACX,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAcf,CAAC;AACX,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAiElD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,MAAM,CAI3F;AAED,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,WAAW,CAAC;AAqB1D,wBAAgB,2BAA2B,CAC1C,KAAK,EAAE,OAAO,EACd,IAAI,GAAE;IACL,IAAI,CAAC,EAAE,mBAAmB,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;CACf,GACJ,MAAM,CAwER;AAED,wBAAgB,4BAA4B,CAC3C,KAAK,EAAE,OAAO,EACd,IAAI,GAAE;IACL,IAAI,CAAC,EAAE,mBAAmB,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;CACf,GACJ,MAAM,CAiBR;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAEzD;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,MAAM,EAAE,CAoB1F"}

package/dist/hud.js

@@ -0,0 +1,269 @@
+import { z } from "zod";
+export const HUD_CONTRACT_VERSION = 1;
+const NonEmptyTextSchema = z.string().trim().min(1);
+export const HudToneSchema = z.enum(["info", "success", "warning", "error", "muted", "accent", "dim"]);
+export const HudActionKindSchema = z.enum(["primary", "secondary", "danger"]);
+export const HudChipSchema = z
+    .object({
+    key: NonEmptyTextSchema,
+    label: NonEmptyTextSchema,
+    tone: HudToneSchema.optional(),
+})
+    .strict();
+export const HudKvItemSchema = z
+    .object({
+    key: NonEmptyTextSchema,
+    label: NonEmptyTextSchema,
+    value: NonEmptyTextSchema,
+    tone: HudToneSchema.optional(),
+})
+    .strict();
+export const HudChecklistItemSchema = z
+    .object({
+    id: NonEmptyTextSchema,
+    label: NonEmptyTextSchema,
+    done: z.boolean(),
+})
+    .strict();
+export const HudSectionSchema = z.discriminatedUnion("kind", [
+    z
+        .object({
+        kind: z.literal("kv"),
+        title: NonEmptyTextSchema.optional(),
+        items: z.array(HudKvItemSchema).default([]),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("checklist"),
+        title: NonEmptyTextSchema.optional(),
+        items: z.array(HudChecklistItemSchema).default([]),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("activity"),
+        title: NonEmptyTextSchema.optional(),
+        lines: z.array(NonEmptyTextSchema).default([]),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("text"),
+        title: NonEmptyTextSchema.optional(),
+        text: NonEmptyTextSchema,
+        tone: HudToneSchema.optional(),
+    })
+        .strict(),
+]);
+export const HudActionSchema = z
+    .object({
+    id: NonEmptyTextSchema,
+    label: NonEmptyTextSchema,
+    command_text: NonEmptyTextSchema,
+    kind: HudActionKindSchema.optional(),
+})
+    .strict();
+export const HudDocSchema = z
+    .object({
+    v: z.literal(HUD_CONTRACT_VERSION).default(HUD_CONTRACT_VERSION),
+    hud_id: NonEmptyTextSchema,
+    title: NonEmptyTextSchema,
+    scope: NonEmptyTextSchema.nullable().default(null),
+    chips: z.array(HudChipSchema).default([]),
+    sections: z.array(HudSectionSchema).default([]),
+    actions: z.array(HudActionSchema).default([]),
+    snapshot_compact: NonEmptyTextSchema,
+    snapshot_multiline: NonEmptyTextSchema.optional(),
+    updated_at_ms: z.number().int().nonnegative(),
+    metadata: z.record(z.string(), z.unknown()).default({}),
+})
+    .strict();
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseHudDocCandidate(value) {
+    const parsed = HudDocSchema.safeParse(value);
+    if (!parsed.success) {
+        return null;
+    }
+    return parsed.data;
+}
+function deterministicHudDocChoice(a, b) {
+    if (a.updated_at_ms !== b.updated_at_ms) {
+        return a.updated_at_ms > b.updated_at_ms ? a : b;
+    }
+    const left = stableSerializeJson(a);
+    const right = stableSerializeJson(b);
+    return left <= right ? a : b;
+}
+function hudDocCandidates(input) {
+    if (Array.isArray(input)) {
+        return input;
+    }
+    if (isPlainObject(input)) {
+        return [input];
+    }
+    return [];
+}
+function normalizedHudDocLimit(limit) {
+    if (typeof limit !== "number" || !Number.isFinite(limit)) {
+        return 12;
+    }
+    const parsed = Math.trunc(limit);
+    if (parsed < 1) {
+        return 1;
+    }
+    if (parsed > 64) {
+        return 64;
+    }
+    return parsed;
+}
+function canonicalizeJson(value) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => canonicalizeJson(entry));
+    }
+    if (!isPlainObject(value)) {
+        return value;
+    }
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+        const nextValue = value[key];
+        if (nextValue === undefined) {
+            continue;
+        }
+        out[key] = canonicalizeJson(nextValue);
+    }
+    return out;
+}
+export function stableSerializeJson(value, opts = {}) {
+    const normalized = canonicalizeJson(value);
+    const text = JSON.stringify(normalized, null, opts.pretty ? 2 : undefined);
+    return text ?? "null";
+}
+function truncateText(value, maxChars) {
+    if (maxChars <= 0) {
+        return "";
+    }
+    if (value.length <= maxChars) {
+        return value;
+    }
+    if (maxChars <= 1) {
+        return "…";
+    }
+    return `${value.slice(0, maxChars - 1)}…`;
+}
+function appendOverflowLine(lines, hiddenCount) {
+    if (hiddenCount > 0) {
+        lines.push(`… (+${hiddenCount} more)`);
+    }
+}
+export function serializeHudDocTextFallback(input, opts = {}) {
+    const doc = parseHudDocCandidate(input);
+    if (!doc) {
+        return "";
+    }
+    const mode = opts.mode ?? "multiline";
+    const maxChars = typeof opts.maxChars === "number" && Number.isFinite(opts.maxChars) ? Math.max(32, Math.trunc(opts.maxChars)) : 8_192;
+    if (mode === "compact") {
+        const compact = `${doc.title} · ${doc.snapshot_compact}`;
+        return truncateText(compact, maxChars);
+    }
+    const maxSectionItems = typeof opts.maxSectionItems === "number" && Number.isFinite(opts.maxSectionItems)
+        ? Math.max(1, Math.trunc(opts.maxSectionItems))
+        : 8;
+    const maxActions = typeof opts.maxActions === "number" && Number.isFinite(opts.maxActions) ? Math.max(1, Math.trunc(opts.maxActions)) : 4;
+    const lines = [];
+    lines.push(`${doc.title} [${doc.hud_id}]`);
+    if (doc.scope) {
+        lines.push(`scope: ${doc.scope}`);
+    }
+    if (doc.chips.length > 0) {
+        lines.push(`chips: ${doc.chips.map((chip) => chip.label).join(" · ")}`);
+    }
+    for (const section of doc.sections) {
+        const title = section.title ? ` (${section.title})` : "";
+        switch (section.kind) {
+            case "kv": {
+                lines.push(`section: kv${title}`);
+                const visible = section.items.slice(0, maxSectionItems);
+                for (const item of visible) {
+                    lines.push(`- ${item.label}: ${item.value}`);
+                }
+                appendOverflowLine(lines, section.items.length - visible.length);
+                break;
+            }
+            case "checklist": {
+                lines.push(`section: checklist${title}`);
+                const visible = section.items.slice(0, maxSectionItems);
+                for (const item of visible) {
+                    lines.push(`- [${item.done ? "x" : " "}] ${item.label}`);
+                }
+                appendOverflowLine(lines, section.items.length - visible.length);
+                break;
+            }
+            case "activity": {
+                lines.push(`section: activity${title}`);
+                const visible = section.lines.slice(0, maxSectionItems);
+                for (const line of visible) {
+                    lines.push(`- ${line}`);
+                }
+                appendOverflowLine(lines, section.lines.length - visible.length);
+                break;
+            }
+            case "text":
+                lines.push(`section: text${title}`);
+                lines.push(`- ${section.text}`);
+                break;
+        }
+    }
+    if (doc.actions.length > 0) {
+        lines.push("actions:");
+        const visible = doc.actions.slice(0, maxActions);
+        for (const action of visible) {
+            lines.push(`- ${action.label}: ${action.command_text}`);
+        }
+        appendOverflowLine(lines, doc.actions.length - visible.length);
+    }
+    return truncateText(lines.join("\n"), maxChars);
+}
+export function serializeHudDocsTextFallback(input, opts = {}) {
+    const docs = normalizeHudDocs(input, { maxDocs: opts.maxDocs });
+    if (docs.length === 0) {
+        return "";
+    }
+    const mode = opts.mode ?? "multiline";
+    const rendered = docs
+        .map((doc) => serializeHudDocTextFallback(doc, {
+        mode,
+        maxChars: opts.maxChars,
+        maxSectionItems: opts.maxSectionItems,
+        maxActions: opts.maxActions,
+    }))
+        .filter((value) => value.length > 0);
+    return rendered.join(mode === "compact" ? " | " : "\n\n");
+}
+export function parseHudDoc(input) {
+    return parseHudDocCandidate(input);
+}
+export function normalizeHudDocs(input, opts = {}) {
+    const maxDocs = normalizedHudDocLimit(opts.maxDocs);
+    const byId = new Map();
+    for (const candidate of hudDocCandidates(input)) {
+        const parsed = parseHudDocCandidate(candidate);
+        if (!parsed) {
+            continue;
+        }
+        const current = byId.get(parsed.hud_id);
+        if (!current) {
+            byId.set(parsed.hud_id, parsed);
+            continue;
+        }
+        byId.set(parsed.hud_id, deterministicHudDocChoice(current, parsed));
+    }
+    const docs = [...byId.values()].sort((left, right) => left.hud_id.localeCompare(right.hud_id));
+    if (docs.length <= maxDocs) {
+        return docs;
+    }
+    return docs.slice(0, maxDocs);
+}

package/dist/hud_runtime.d.ts

@@ -0,0 +1,36 @@
+import { type HudDoc } from "./hud.js";
+export type HudProviderRuntimeApi<Msg> = {
+    dispatch: (message: Msg) => void;
+};
+export type HudProviderReducerResult<State, Effect> = {
+    state: State;
+    effects?: Effect[];
+};
+export type HudProvider<State, Msg, Effect> = {
+    id: string;
+    initialState: () => State;
+    reduce: (state: State, message: Msg) => HudProviderReducerResult<State, Effect>;
+    runEffect?: (effect: Effect, api: HudProviderRuntimeApi<Msg>) => void | Promise<void>;
+    view: (state: State) => HudDoc | HudDoc[] | null;
+};
+export type HudRuntimeSnapshot = {
+    provider_id: string;
+    hud_docs: HudDoc[];
+};
+export type HudRuntimeListener = (snapshot: HudRuntimeSnapshot) => void;
+export type HudRuntimeDispatchResult = {
+    provider_id: string;
+    messages_processed: number;
+    effects_processed: number;
+    hud_docs: HudDoc[];
+};
+export declare class HudRuntime {
+    #private;
+    register<State, Msg, Effect>(provider: HudProvider<State, Msg, Effect>): void;
+    unregister(providerId: string): boolean;
+    listProviders(): string[];
+    subscribe(listener: HudRuntimeListener): () => void;
+    snapshot(providerId: string): HudRuntimeSnapshot;
+    dispatch<Msg>(providerId: string, message: Msg): Promise<HudRuntimeDispatchResult>;
+}
+//# sourceMappingURL=hud_runtime.d.ts.map

package/dist/hud_runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hud_runtime.d.ts","sourceRoot":"","sources":["../src/hud_runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAoB,MAAM,UAAU,CAAC;AAEzD,MAAM,MAAM,qBAAqB,CAAC,GAAG,IAAI;IACxC,QAAQ,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,IAAI,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,wBAAwB,CAAC,KAAK,EAAE,MAAM,IAAI;IACrD,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,WAAW,CAAC,KAAK,EAAE,GAAG,EAAE,MAAM,IAAI;IAC7C,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,KAAK,CAAC;IAC1B,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK,wBAAwB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAChF,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,qBAAqB,CAAC,GAAG,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtF,IAAI,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC;CACjD,CAAC;AASF,MAAM,MAAM,kBAAkB,GAAG;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,CAAC,QAAQ,EAAE,kBAAkB,KAAK,IAAI,CAAC;AAExE,MAAM,MAAM,wBAAwB,GAAG;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AAEF,qBAAa,UAAU;;IAIf,QAAQ,CAAC,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,CAAC,KAAK,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,IAAI;IAe7E,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAQvC,aAAa,IAAI,MAAM,EAAE;IAIzB,SAAS,CAAC,QAAQ,EAAE,kBAAkB,GAAG,MAAM,IAAI;IAOnD,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB;IAS1C,QAAQ,CAAC,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,GAAG,OAAO,CAAC,wBAAwB,CAAC;CAmE/F"}

package/dist/hud_runtime.js

@@ -0,0 +1,105 @@
+import { normalizeHudDocs } from "./hud.js";
+export class HudRuntime {
+    #providers = new Map();
+    #listeners = new Set();
+    register(provider) {
+        const providerId = provider.id.trim();
+        if (providerId.length === 0) {
+            throw new Error("provider id must be non-empty");
+        }
+        if (this.#providers.has(providerId)) {
+            throw new Error(`provider already registered: ${providerId}`);
+        }
+        this.#providers.set(providerId, {
+            provider: provider,
+            state: provider.initialState(),
+        });
+        this.#emit(providerId);
+    }
+    unregister(providerId) {
+        const normalized = providerId.trim();
+        if (normalized.length === 0) {
+            return false;
+        }
+        return this.#providers.delete(normalized);
+    }
+    listProviders() {
+        return [...this.#providers.keys()].sort((a, b) => a.localeCompare(b));
+    }
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        return () => {
+            this.#listeners.delete(listener);
+        };
+    }
+    snapshot(providerId) {
+        const record = this.#provider(providerId);
+        const hudDocs = this.#hudDocs(record.provider, record.state);
+        return {
+            provider_id: providerId,
+            hud_docs: hudDocs,
+        };
+    }
+    async dispatch(providerId, message) {
+        const record = this.#provider(providerId);
+        const provider = record.provider;
+        const messageQueue = [message];
+        let messagesProcessed = 0;
+        let effectsProcessed = 0;
+        while (messageQueue.length > 0) {
+            const currentMessage = messageQueue.shift();
+            messagesProcessed += 1;
+            const reduced = provider.reduce(record.state, currentMessage);
+            record.state = reduced.state;
+            const effects = Array.isArray(reduced.effects) ? reduced.effects : [];
+            for (const effect of effects) {
+                effectsProcessed += 1;
+                if (!provider.runEffect) {
+                    continue;
+                }
+                const api = {
+                    dispatch: (nextMessage) => {
+                        messageQueue.push(nextMessage);
+                    },
+                };
+                await provider.runEffect(effect, api);
+            }
+        }
+        const snapshot = this.#emit(providerId);
+        return {
+            provider_id: providerId,
+            messages_processed: messagesProcessed,
+            effects_processed: effectsProcessed,
+            hud_docs: snapshot.hud_docs,
+        };
+    }
+    #provider(providerId) {
+        const normalized = providerId.trim();
+        if (normalized.length === 0) {
+            throw new Error("provider id must be non-empty");
+        }
+        const record = this.#providers.get(normalized);
+        if (!record) {
+            throw new Error(`unknown provider: ${normalized}`);
+        }
+        return record;
+    }
+    #hudDocs(provider, state) {
+        const viewed = provider.view(state);
+        if (viewed == null) {
+            return [];
+        }
+        return normalizeHudDocs(Array.isArray(viewed) ? viewed : [viewed]);
+    }
+    #emit(providerId) {
+        const record = this.#provider(providerId);
+        const snapshot = {
+            provider_id: providerId,
+            hud_docs: this.#hudDocs(record.provider, record.state),
+        };
+        for (const listener of this.#listeners) {
+            listener(snapshot);
+        }
+        return snapshot;
+    }
+}

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export * from "./events.js";
+export * from "./hud.js";
+export * from "./hud_runtime.js";
 export * from "./ids.js";
 export * from "./persistence.js";
 export * from "./spec.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,cAAc,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,cAAc,WAAW,CAAC"}

package/dist/index.js

@@ -1,4 +1,6 @@
 export * from "./events.js";
+export * from "./hud.js";
+export * from "./hud_runtime.js";
 export * from "./ids.js";
 export * from "./persistence.js";
 export * from "./spec.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@femtomc/mu-core",
-  "version": "26.2.99",
+  "version": "26.2.101",
   "description": "Core primitives for mu: IDs, events, schemas, and persistence interfaces.",
   "keywords": [
     "mu",