@femtomc/mu-core 26.2.107 → 26.2.109

package/README.md

@@ -34,28 +34,15 @@ 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(...)`
-- `resolveHudStylePresetName(...)`, `applyHudStylePreset(...)`, `hudStylePresetWarnings(...)`
-- `serializeHudDocTextFallback(...)`, `serializeHudDocsTextFallback(...)`
-- `stableSerializeJson(...)`
-- `HudRuntime` + `HudProvider` for provider registration, reducer updates, ordered effect execution, and HUD snapshot emission
-
-`HudDoc` also supports optional presentation hints (`title_style`, `snapshot_style`, chip/item/section/action style objects) and metadata style presets (`metadata.style_preset` currently `planning|subagents`) so renderers can opt into richer emphasis while preserving deterministic plain-text fallbacks.
-
-These are runtime-agnostic primitives intended for shared HUD capture/render pipelines.
-
 ## UI contract helpers
 
 Interactive UI documents are modeled as first-class, versioned contracts that describe renderable components, actions, and revisions so any rendering surface can stay in sync with agents. `@femtomc/mu-core` exposes the following helpers:
 
 - `UI_CONTRACT_VERSION`, `UiDocSchema`, `UiRevisionSchema`, `UiComponentSchema`, and `UiActionSchema` for validating document payloads.
 - `parseUiDoc(...)`, `normalizeUiDocs(...)`, and `uiDocRevisionConflict(...)` for deterministic selection, conflict detection, and safe merging of candidate documents.
+- `resolveUiStatusProfileName(...)` and `uiStatusProfileWarnings(...)` for advisory validation of profile-scoped status docs (`planning`, `subagents`, `control-flow`, `model-routing`) carried in `metadata.profile`.
 - `UiEventSchema` + `parseUiEvent(...)` for structured event payloads emitted by frontends (every event includes `ui_id`, `action_id`, the originating `revision`, optional `callback_token`, `payload`, and `created_at_ms`).
+- `stableSerializeJson(...)` for deterministic metadata serialization and revision tie-breaking.
 
 ### Field limits
 

package/dist/index.d.ts

@@ -1,6 +1,4 @@
 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,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,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,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC"}

package/dist/index.js

@@ -1,6 +1,4 @@
 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/ui.d.ts

@@ -1,4 +1,14 @@
 import { z } from "zod";
+export declare const UiToneSchema: z.ZodEnum<{
+    error: "error";
+    success: "success";
+    info: "info";
+    warning: "warning";
+    muted: "muted";
+    accent: "accent";
+    dim: "dim";
+}>;
+export type UiTone = z.infer<typeof UiToneSchema>;
 export declare const UI_CONTRACT_VERSION: 1;
 export declare const UiListItemSchema: z.ZodObject<{
     id: z.ZodString;
@@ -6,8 +16,8 @@ export declare const UiListItemSchema: z.ZodObject<{
     detail: z.ZodOptional<z.ZodString>;
     tone: z.ZodOptional<z.ZodEnum<{
         error: "error";
-        info: "info";
         success: "success";
+        info: "info";
         warning: "warning";
         muted: "muted";
         accent: "accent";
@@ -20,8 +30,8 @@ export declare const UiKeyValueRowSchema: z.ZodObject<{
     value: z.ZodString;
     tone: z.ZodOptional<z.ZodEnum<{
         error: "error";
-        info: "info";
         success: "success";
+        info: "info";
         warning: "warning";
         muted: "muted";
         accent: "accent";
@@ -35,8 +45,8 @@ export declare const UiComponentTextSchema: z.ZodObject<{
     text: z.ZodString;
     tone: z.ZodOptional<z.ZodEnum<{
         error: "error";
-        info: "info";
         success: "success";
+        info: "info";
         warning: "warning";
         muted: "muted";
         accent: "accent";
@@ -55,8 +65,8 @@ export declare const UiComponentListSchema: z.ZodObject<{
         detail: z.ZodOptional<z.ZodString>;
         tone: z.ZodOptional<z.ZodEnum<{
             error: "error";
-            info: "info";
             success: "success";
+            info: "info";
             warning: "warning";
             muted: "muted";
             accent: "accent";
@@ -74,8 +84,8 @@ export declare const UiComponentKeyValueSchema: z.ZodObject<{
         value: z.ZodString;
         tone: z.ZodOptional<z.ZodEnum<{
             error: "error";
-            info: "info";
             success: "success";
+            info: "info";
             warning: "warning";
             muted: "muted";
             accent: "accent";
@@ -95,8 +105,8 @@ export declare const UiComponentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     text: z.ZodString;
     tone: z.ZodOptional<z.ZodEnum<{
         error: "error";
-        info: "info";
         success: "success";
+        info: "info";
         warning: "warning";
         muted: "muted";
         accent: "accent";
@@ -113,8 +123,8 @@ export declare const UiComponentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         detail: z.ZodOptional<z.ZodString>;
         tone: z.ZodOptional<z.ZodEnum<{
             error: "error";
-            info: "info";
             success: "success";
+            info: "info";
             warning: "warning";
             muted: "muted";
             accent: "accent";
@@ -131,8 +141,8 @@ export declare const UiComponentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         value: z.ZodString;
         tone: z.ZodOptional<z.ZodEnum<{
             error: "error";
-            info: "info";
             success: "success";
+            info: "info";
             warning: "warning";
             muted: "muted";
             accent: "accent";
@@ -185,8 +195,8 @@ export declare const UiDocSchema: z.ZodObject<{
         text: z.ZodString;
         tone: z.ZodOptional<z.ZodEnum<{
             error: "error";
-            info: "info";
             success: "success";
+            info: "info";
             warning: "warning";
             muted: "muted";
             accent: "accent";
@@ -203,8 +213,8 @@ export declare const UiDocSchema: z.ZodObject<{
             detail: z.ZodOptional<z.ZodString>;
             tone: z.ZodOptional<z.ZodEnum<{
                 error: "error";
-                info: "info";
                 success: "success";
+                info: "info";
                 warning: "warning";
                 muted: "muted";
                 accent: "accent";
@@ -221,8 +231,8 @@ export declare const UiDocSchema: z.ZodObject<{
             value: z.ZodString;
             tone: z.ZodOptional<z.ZodEnum<{
                 error: "error";
-                info: "info";
                 success: "success";
+                info: "info";
                 warning: "warning";
                 muted: "muted";
                 accent: "accent";
@@ -258,6 +268,8 @@ export declare const UiDocSchema: z.ZodObject<{
     metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strict>;
 export type UiDoc = z.infer<typeof UiDocSchema>;
+export declare const UI_STATUS_PROFILE_NAMES: readonly ["planning", "subagents", "control-flow", "model-routing"];
+export type UiStatusProfileName = (typeof UI_STATUS_PROFILE_NAMES)[number];
 export declare const UiEventSchema: z.ZodObject<{
     ui_id: z.ZodString;
     action_id: z.ZodString;
@@ -272,7 +284,12 @@ export declare const UiEventSchema: z.ZodObject<{
     metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strict>;
 export type UiEvent = z.infer<typeof UiEventSchema>;
+export declare function stableSerializeJson(value: unknown, opts?: {
+    pretty?: boolean;
+}): string;
 export declare function parseUiDoc(input: unknown): UiDoc | null;
+export declare function resolveUiStatusProfileName(input: unknown): UiStatusProfileName | null;
+export declare function uiStatusProfileWarnings(input: unknown): string[];
 export declare function normalizeUiDocs(input: unknown, opts?: {
     maxDocs?: number;
 }): UiDoc[];

package/dist/ui.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,mBAAmB,EAAG,CAAU,CAAC;AAsB9C,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;kBAOnB,CAAC;AACX,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,mBAAmB;;;;;;;;;;;;kBAMtB,CAAC;AACX,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;kBAQxB,CAAC;AACX,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;kBAQxB,CAAC;AAEX,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;kBAQ5B,CAAC;AAEX,eAAO,MAAM,wBAAwB;;;;kBAM3B,CAAC;AAEX,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BAK5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,eAAO,MAAM,kBAAkB;;;;;EAAqD,CAAC;AACrF,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,eAAO,MAAM,cAAc;;;;;;;;;;;;;;kBAWjB,CAAC;AACX,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD,eAAO,MAAM,gBAAgB;;;kBAKnB,CAAC;AACX,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAYd,CAAC;AACX,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEhD,eAAO,MAAM,aAAa;;;;;;;;;;;;kBAWhB,CAAC;AACX,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAkDpD,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,GAAG,IAAI,CAEvD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,KAAK,EAAE,CAoBxF;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAQxE;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI,CAM3D"}
+{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"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"}

package/dist/ui.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { HudToneSchema, stableSerializeJson } from "./hud.js";
+export const UiToneSchema = z.enum(["info", "success", "warning", "error", "muted", "accent", "dim"]);
 export const UI_CONTRACT_VERSION = 1;
 const UI_DOC_TITLE_MAX_LENGTH = 256;
 const UI_DOC_SUBTITLE_MAX_LENGTH = 512;
@@ -24,14 +24,14 @@ export const UiListItemSchema = z
     id: NonEmptyId,
     label: NonEmptyText(UI_ACTION_LABEL_MAX_LENGTH),
     detail: NonEmptyText(UI_LIST_ITEM_DETAIL_MAX_LENGTH).optional(),
-    tone: HudToneSchema.optional(),
+    tone: UiToneSchema.optional(),
 })
     .strict();
 export const UiKeyValueRowSchema = z
     .object({
     key: NonEmptyText(UI_KEY_MAX_LENGTH),
     value: NonEmptyText(UI_VALUE_MAX_LENGTH),
-    tone: HudToneSchema.optional(),
+    tone: UiToneSchema.optional(),
 })
     .strict();
 export const UiComponentTextSchema = z
@@ -39,7 +39,7 @@ export const UiComponentTextSchema = z
     kind: z.literal("text"),
     id: NonEmptyId,
     text: NonEmptyText(UI_TEXT_COMPONENT_MAX_LENGTH),
-    tone: HudToneSchema.optional(),
+    tone: UiToneSchema.optional(),
     metadata: z.record(z.string(), z.unknown()).default({}),
 })
     .strict();
@@ -106,6 +106,7 @@ export const UiDocSchema = z
     metadata: z.record(z.string(), z.unknown()).default({}),
 })
     .strict();
+export const UI_STATUS_PROFILE_NAMES = ["planning", "subagents", "control-flow", "model-routing"];
 export const UiEventSchema = z
     .object({
     ui_id: NonEmptyId,
@@ -128,6 +129,129 @@ function parseUiDocCandidate(value) {
     }
     return parsed.data;
 }
+const UI_PROFILE_VARIANTS = ["status", "interactive"];
+const UI_STATUS_PROFILE_UI_IDS = {
+    planning: "ui:planning",
+    subagents: "ui:subagents",
+    "control-flow": "ui:control-flow",
+    "model-routing": "ui:model-routing",
+};
+const UI_STATUS_PROFILE_COMPONENT_RECOMMENDATIONS = {
+    planning: ["key_value", "list"],
+    subagents: ["key_value", "list"],
+    "control-flow": ["key_value"],
+    "model-routing": ["key_value", "list"],
+};
+const UI_PLANNING_STATUS_ROW_KEY_ALIASES = {
+    phase: ["phase"],
+    waiting: ["waiting", "waiting_on_user"],
+    confidence: ["confidence", "conf"],
+    next: ["next", "next_action"],
+    blocker: ["blocker"],
+};
+const UI_PLANNING_CHECKLIST_MIN_ITEMS = 3;
+function isUiStatusProfileName(value) {
+    return UI_STATUS_PROFILE_NAMES.includes(value);
+}
+function isUiProfileVariant(value) {
+    return UI_PROFILE_VARIANTS.includes(value);
+}
+function uiProfileMetadata(doc) {
+    const raw = doc.metadata.profile;
+    if (!isPlainObject(raw)) {
+        return null;
+    }
+    return raw;
+}
+function uiStatusProfileNameFromDoc(doc) {
+    const profile = uiProfileMetadata(doc);
+    if (!profile) {
+        return null;
+    }
+    const raw = profile.id;
+    if (typeof raw !== "string") {
+        return null;
+    }
+    const normalized = raw.trim().toLowerCase();
+    if (!normalized || !isUiStatusProfileName(normalized)) {
+        return null;
+    }
+    return normalized;
+}
+function hasUiComponentKind(doc, kind) {
+    return doc.components.some((component) => component.kind === kind);
+}
+function hasProfileSnapshotCompact(profile) {
+    const snapshot = profile.snapshot;
+    if (!isPlainObject(snapshot)) {
+        return false;
+    }
+    const compact = snapshot.compact;
+    return typeof compact === "string" && compact.trim().length > 0;
+}
+function normalizeStatusRowKey(key) {
+    return key
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_");
+}
+function keyValueStatusRows(doc) {
+    const rows = new Set();
+    for (const component of doc.components) {
+        if (component.kind !== "key_value") {
+            continue;
+        }
+        for (const row of component.rows) {
+            rows.add(normalizeStatusRowKey(row.key));
+        }
+    }
+    return rows;
+}
+function firstChecklistComponent(doc) {
+    for (const component of doc.components) {
+        if (component.kind === "list") {
+            return component;
+        }
+    }
+    return null;
+}
+function hasPlanningMetadataField(doc, key) {
+    const value = doc.metadata[key];
+    if (key === "waiting_on_user") {
+        return typeof value === "boolean";
+    }
+    return typeof value === "string" && value.trim().length > 0;
+}
+function planningStatusProfileWarnings(doc) {
+    const warnings = [];
+    const statusRows = keyValueStatusRows(doc);
+    for (const [field, aliases] of Object.entries(UI_PLANNING_STATUS_ROW_KEY_ALIASES)) {
+        const hasField = aliases.some((alias) => statusRows.has(alias));
+        if (!hasField) {
+            warnings.push(`profile.id=planning recommends key_value row key=${field}`);
+        }
+    }
+    const checklist = firstChecklistComponent(doc);
+    if (checklist) {
+        if (checklist.items.length < UI_PLANNING_CHECKLIST_MIN_ITEMS) {
+            warnings.push(`profile.id=planning recommends checklist lists with at least ${UI_PLANNING_CHECKLIST_MIN_ITEMS} items`);
+        }
+        const detailedItems = checklist.items.filter((item) => typeof item.detail === "string" && item.detail.trim().length > 0).length;
+        if (detailedItems === 0) {
+            warnings.push("profile.id=planning recommends checklist item detail values (for example done/pending)");
+        }
+    }
+    if (!hasPlanningMetadataField(doc, "phase")) {
+        warnings.push("profile.id=planning recommends metadata.phase");
+    }
+    if (!hasPlanningMetadataField(doc, "waiting_on_user")) {
+        warnings.push("profile.id=planning recommends metadata.waiting_on_user");
+    }
+    if (!hasPlanningMetadataField(doc, "confidence")) {
+        warnings.push("profile.id=planning recommends metadata.confidence");
+    }
+    return warnings;
+}
 function uiDocCandidates(input) {
     if (Array.isArray(input)) {
         return input;
@@ -150,6 +274,28 @@ function normalizedUiDocLimit(limit) {
     }
     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 deterministicUiDocChoice(left, right) {
     if (left.revision.version !== right.revision.version) {
         return left.revision.version > right.revision.version ? left : right;
@@ -164,6 +310,63 @@ function deterministicUiDocChoice(left, right) {
 export function parseUiDoc(input) {
     return parseUiDocCandidate(input);
 }
+export function resolveUiStatusProfileName(input) {
+    const doc = parseUiDocCandidate(input);
+    if (!doc) {
+        return null;
+    }
+    return uiStatusProfileNameFromDoc(doc);
+}
+export function uiStatusProfileWarnings(input) {
+    const doc = parseUiDocCandidate(input);
+    if (!doc) {
+        return [];
+    }
+    const profileName = uiStatusProfileNameFromDoc(doc);
+    if (!profileName) {
+        return [];
+    }
+    const warnings = [];
+    const profile = uiProfileMetadata(doc);
+    if (!profile) {
+        return warnings;
+    }
+    const rawVariant = typeof profile.variant === "string" ? profile.variant.trim().toLowerCase() : "";
+    let variant = "status";
+    if (rawVariant.length > 0) {
+        if (isUiProfileVariant(rawVariant)) {
+            variant = rawVariant;
+        }
+        else {
+            warnings.push(`profile.id=${profileName} has unsupported metadata.profile.variant=${rawVariant}`);
+        }
+    }
+    if (variant !== "status") {
+        warnings.push(`profile.id=${profileName} status validation expects metadata.profile.variant=status (got ${variant})`);
+    }
+    const expectedUiId = UI_STATUS_PROFILE_UI_IDS[profileName];
+    if (doc.ui_id !== expectedUiId) {
+        warnings.push(`profile.id=${profileName} expects ui_id=${expectedUiId} (got ${doc.ui_id})`);
+    }
+    if (!doc.summary) {
+        warnings.push(`profile.id=${profileName} recommends summary for deterministic status fallback`);
+    }
+    if (!hasProfileSnapshotCompact(profile)) {
+        warnings.push(`profile.id=${profileName} recommends metadata.profile.snapshot.compact`);
+    }
+    if (doc.actions.length > 0) {
+        warnings.push(`profile.id=${profileName} status docs should omit actions (got ${doc.actions.length})`);
+    }
+    for (const kind of UI_STATUS_PROFILE_COMPONENT_RECOMMENDATIONS[profileName]) {
+        if (!hasUiComponentKind(doc, kind)) {
+            warnings.push(`profile.id=${profileName} recommends a ${kind} component`);
+        }
+    }
+    if (profileName === "planning") {
+        warnings.push(...planningStatusProfileWarnings(doc));
+    }
+    return warnings;
+}
 export function normalizeUiDocs(input, opts = {}) {
     const maxDocs = normalizedUiDocLimit(opts.maxDocs);
     const byId = new Map();

package/package.json

@@ -1,34 +1,34 @@
 {
-  "name": "@femtomc/mu-core",
-  "version": "26.2.107",
-  "description": "Core primitives for mu: IDs, events, schemas, and persistence interfaces.",
-  "keywords": [
-    "mu",
-    "agent",
-    "core",
-    "events"
-  ],
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    },
-    "./browser": {
-      "types": "./dist/browser/index.d.ts",
-      "default": "./dist/browser/index.js"
-    },
-    "./node": {
-      "types": "./dist/node/index.d.ts",
-      "default": "./dist/node/index.js"
-    }
-  },
-  "files": [
-    "dist/**"
-  ],
-  "dependencies": {
-    "zod": "^4.1.9"
-  }
+	"name": "@femtomc/mu-core",
+	"version": "26.2.109",
+	"description": "Core primitives for mu: IDs, events, schemas, and persistence interfaces.",
+	"keywords": [
+		"mu",
+		"agent",
+		"core",
+		"events"
+	],
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		},
+		"./browser": {
+			"types": "./dist/browser/index.d.ts",
+			"default": "./dist/browser/index.js"
+		},
+		"./node": {
+			"types": "./dist/node/index.d.ts",
+			"default": "./dist/node/index.js"
+		}
+	},
+	"files": [
+		"dist/**"
+	],
+	"dependencies": {
+		"zod": "^4.1.9"
+	}
 }