@cosmicdrift/kumiko-framework 0.240.0 → 0.242.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.240.0",
+  "version": "0.242.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -198,7 +198,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.240.0",
+    "@cosmicdrift/kumiko-types": "0.242.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -214,7 +214,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.240.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.242.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,28 @@
 [
+  {
+    "version": "0.241.0",
+    "type": "improvement",
+    "title": "ProjectionDetailScreenDefinition gains singleton: boolean for self-service screens bound to a caller-scoped query (fw#2312).",
+    "detail": "A `projectionDetail` screen previously always resolved its row from a path id — the only case `ProjectionDetailBody` handled — so binding one to a `me`-style query (e.g. `user:query:user:me`) rendered nothing but a \"missing id\" error banner. With `singleton: true`, the query is called without the `idParam` key (there is no id to send) and any path id is ignored rather than forwarded into the query or into extension sections' entity-id resolution — a singleton row is server-picked, so no client-supplied id can reach it. The boot validator rejects `idParam` or `detailFor` declared together with `singleton` (both are meaningless once the server owns row selection)."
+  },
+  {
+    "version": "0.241.0",
+    "type": "improvement",
+    "title": "DashboardStatPanel gains an optional params field for static query parameters (fw#2312).",
+    "detail": "`DashboardStatPanel.params?: Readonly<Record<string, unknown>>` (`@cosmicdrift/kumiko-types`) is merged under the panel's dynamic `filterParams` by `@cosmicdrift/kumiko-renderer-web`'s dashboard body — lets a panel pin a value (e.g. a status facet) the screen-wide filter doesn't cover, without needing its own query. Additive; existing `dashboard` screens are unaffected."
+  },
+  {
+    "version": "0.241.0",
+    "type": "improvement",
+    "title": "EditFieldSpec.renderer gains a json format for pretty-printed structured fields (fw#2312).",
+    "detail": "`FieldFormatRegistry.json: { indent?: number }` (`@cosmicdrift/kumiko-types`, resolved by `@cosmicdrift/kumiko-headless`) — set `renderer: { format: \"json\", indent: 2 }` on an `EditFieldSpec` to pretty-print a JSON-string field instead of showing the raw escaped string. Pairs with the new `JsonView` primitive below when `@cosmicdrift/kumiko-renderer-web` is in use."
+  },
+  {
+    "version": "0.241.0",
+    "type": "improvement",
+    "title": "Optional JsonView primitive for structured, syntax-highlighted JSON display (fw#2312).",
+    "detail": "`CorePrimitives.JsonView` (`@cosmicdrift/kumiko-renderer`, web impl `DefaultJsonView` in `@cosmicdrift/kumiko-renderer-web`) receives the raw value (not a pre-stringified string) and stringifies + tokenizes itself; never throws on circular references, `BigInt`, or other non-serializable input. Optional on `CorePrimitives`, so an existing partial `CorePrimitives` test mock/provider keeps compiling unchanged — every call site (renderer's `format: \"json\"` fields, the jsonb/embedded/files/images fallback banner, `EditorPanel`'s unresolved-target args display) falls back to the prior `<Text>`/`<pre>` rendering when no `JsonView` is registered. A custom `PrimitivesProvider` that wants the improved rendering needs to add a `JsonView` implementation; nothing breaks if it doesn't."
+  },
   {
     "version": "0.235.0",
     "type": "breaking",

package/src/engine/__tests__/projection-detail-singleton.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { withBootValidatorFixture } from "../../testing/boot-validator-fixture";
+import { validateBoot as validateBootRaw } from "../boot-validator";
+import { defineFeature } from "../define-feature";
+import { createEntity, createTextField } from "../factories";
+
+function validateBoot(features: Parameters<typeof validateBootRaw>[0]): void {
+  validateBootRaw(withBootValidatorFixture(features));
+}
+
+// fw#2312: `singleton: true` marks a projectionDetail screen whose query
+// determines the shown row from the caller's context (session), not a row
+// id in the path — a self-service screen like "my profile". idParam names
+// the query-payload key for a path row id, which a singleton screen never
+// sends; detailFor drives the auto-generated "Edit" action's navigation via
+// that same path id (fw#2166). Both combinations are rejected at boot
+// instead of silently winning (idParam ignored / edit button opening a
+// blank create form).
+describe("validateBoot — projectionDetail singleton (fw#2312)", () => {
+  test("singleton + idParam throws", () => {
+    const feature = defineFeature("app", (r) => {
+      r.queryHandler("me", z.object({}), async () => ({ id: "u1" }), {
+        access: { openToAll: true },
+      });
+      r.screen({
+        id: "profile",
+        type: "projectionDetail",
+        query: "app:query:me",
+        singleton: true,
+        idParam: "userId",
+        layout: { sections: [{ title: "s", fields: ["id"] }] },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /Screen "profile" \(projectionDetail\) sets both singleton: true and idParam/,
+    );
+  });
+
+  test("singleton + detailFor throws", () => {
+    const feature = defineFeature("app", (r) => {
+      r.entity("user", createEntity({ fields: { name: createTextField() } }));
+      r.queryHandler("me", z.object({}), async () => ({ id: "u1" }), {
+        access: { openToAll: true },
+      });
+      r.screen({
+        id: "profile",
+        type: "projectionDetail",
+        query: "app:query:me",
+        singleton: true,
+        detailFor: "user",
+        layout: { sections: [{ title: "s", fields: ["id"] }] },
+      });
+      r.screen({
+        id: "user-edit",
+        type: "entityEdit",
+        entity: "user",
+        layout: { sections: [{ columns: 1, fields: ["name"] }] },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /Screen "profile" \(projectionDetail\) sets both singleton: true and detailFor/,
+    );
+  });
+
+  test("singleton without idParam/detailFor boots cleanly", () => {
+    const feature = defineFeature("app", (r) => {
+      r.queryHandler("me", z.object({}), async () => ({ id: "u1" }), {
+        access: { openToAll: true },
+      });
+      r.screen({
+        id: "profile",
+        type: "projectionDetail",
+        query: "app:query:me",
+        singleton: true,
+        layout: { sections: [{ title: "s", fields: ["id"] }] },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+});

package/src/engine/boot-validator/screens.ts

@@ -622,6 +622,26 @@ export function validateScreens(
           `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) has empty or non-string query.`,
         );
       }
+      if (screen.singleton === true && screen.idParam !== undefined) {
+        throw new Error(
+          `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) sets both singleton: true ` +
+            `and idParam — singleton means the server picks the row from the caller's context, so there ` +
+            `is no row id to send under idParam. Remove idParam.`,
+        );
+      }
+      // singleton has no row id in the path, but the auto-generated "Edit"
+      // action (fw#2166, defaultEditAction in kumiko-screen.tsx) navigates
+      // to the detailFor entity's entityEdit screen using that path id —
+      // under singleton it would silently open that screen in CREATE mode
+      // instead of editing the singleton row. Reject rather than let that
+      // win silently, same as the idParam check above.
+      if (screen.singleton === true && screen.detailFor !== undefined) {
+        throw new Error(
+          `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) sets both singleton: true ` +
+            `and detailFor — the auto-generated "Edit" action navigates using the path's row id, which a ` +
+            `singleton screen never has. Remove detailFor, or declare an explicit "edit" action instead.`,
+        );
+      }
       if (screen.layout.sections.length === 0) {
         throw new Error(
           `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) has an empty sections list — ` +

package/src/engine/index.ts

@@ -473,7 +473,13 @@ export type {
   WriteHandlerFn,
   WriteResult,
 } from "./types";
-export { DEFAULT_CURRENCIES, DEFAULT_LOCALES, HookPhases, resolveAgentExposure } from "./types";
+export {
+  DEFAULT_CURRENCIES,
+  DEFAULT_LOCALES,
+  HookPhases,
+  isAgentVisibleScreen,
+  resolveAgentExposure,
+} from "./types";
 export { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers";
 export type {
   AwaitedEventType,

package/src/engine/types/index.ts

@@ -1,7 +1,10 @@
 // Barrel: re-exports all types from @cosmicdrift/kumiko-types, plus the
 // runtime helpers below that stay framework-side.
 
-export { resolveAgentExposure } from "@cosmicdrift/kumiko-types/agent-exposure";
+export {
+  isAgentVisibleScreen,
+  resolveAgentExposure,
+} from "@cosmicdrift/kumiko-types/agent-exposure";
 export type {
   ConfigAccessor,
   ConfigAccessorFactory,

package/src/event-store/__tests__/perf.integration.test.ts

@@ -103,8 +103,8 @@ describe("event-store performance — Gate A", () => {
     );
 
     expect(p95).toBeLessThan(30);
-    // Tail budget: cold-checkpoint/fsync spikes after warm-up, not connection warm-up.
-    expect(p99).toBeLessThan(100);
+    // Tail budget: absorbs cold-checkpoint/fsync spikes (observed up to 102ms at p50=1.2ms) while still catching order-of-magnitude regressions.
+    expect(p99).toBeLessThan(250);
   });
 
   test("read-latency p95 < 25ms for loadAggregate detail reads", async () => {
@@ -145,7 +145,7 @@ describe("event-store performance — Gate A", () => {
     // 25ms budget kept from the original spike doc's 10ms — an
     // order-of-magnitude gate, not an idle-best-case one. Tracking: #325.
     expect(p95).toBeLessThan(25);
-    expect(p99).toBeLessThan(100);
+    expect(p99).toBeLessThan(250);
   });
 
   test("update-latency p95 < 30ms — exercises predecessor-check WHERE EXISTS path", async () => {
@@ -205,7 +205,7 @@ describe("event-store performance — Gate A", () => {
     );
 
     expect(p95).toBeLessThan(30);
-    expect(p99).toBeLessThan(100);
+    expect(p99).toBeLessThan(250);
   });
 
   test("snapshot-load < 50ms for 1000-event aggregate (Gate A)", async () => {