@cosmicdrift/kumiko-framework 0.152.0 → 0.153.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.152.0",
+  "version": "0.153.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>",
@@ -193,7 +193,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.152.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.153.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/engine/__tests__/nav.test.ts

@@ -80,6 +80,86 @@ describe("r.nav() — registration", () => {
   });
 });
 
+describe("r.screen({ nav }) — inline nav sugar", () => {
+  test("synthesizes a nav entry from the screen's id", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", productEntity());
+      r.screen({
+        id: "products",
+        type: "entityList",
+        entity: "product",
+        columns: ["name"],
+        nav: { label: "shop:nav.products", icon: "box", order: 5 },
+      });
+    });
+    expect(feature.navs["products"]).toMatchObject({
+      id: "products",
+      label: "shop:nav.products",
+      icon: "box",
+      order: 5,
+      screen: "shop:screen:products",
+    });
+  });
+
+  test("supports parent like a standalone r.nav()", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.nav({ id: "catalog", label: "x" });
+      r.entity("product", productEntity());
+      r.screen({
+        id: "products",
+        type: "entityList",
+        entity: "product",
+        columns: ["name"],
+        nav: { label: "y", parent: "shop:nav:catalog" },
+      });
+    });
+    expect(feature.navs["products"]?.parent).toBe("shop:nav:catalog");
+  });
+
+  test("passes the same boot-validation as a standalone r.nav()", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", productEntity());
+      r.screen({
+        id: "products",
+        type: "entityList",
+        entity: "product",
+        columns: ["name"],
+        nav: { label: "y" },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("screen without nav registers no nav entry", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", productEntity());
+      r.screen({
+        id: "products",
+        type: "entityList",
+        entity: "product",
+        columns: ["name"],
+      });
+    });
+    expect(feature.navs["products"]).toBeUndefined();
+  });
+
+  test("rejects when a standalone r.nav() already used the screen's id", () => {
+    expect(() =>
+      defineFeature("shop", (r) => {
+        r.nav({ id: "products", label: "standalone" });
+        r.entity("product", productEntity());
+        r.screen({
+          id: "products",
+          type: "entityList",
+          entity: "product",
+          columns: ["name"],
+          nav: { label: "inline" },
+        });
+      }),
+    ).toThrow(/already registered/);
+  });
+});
+
 describe("createRegistry — nav indexing", () => {
   test("indexes nav entries by qualified name", () => {
     const feature = defineFeature("shop", (r) => {

package/src/engine/feature-ast/__tests__/render-roundtrip.test.ts

@@ -358,3 +358,45 @@ describe("renderPattern — single-pattern shape", () => {
     expect(out).toBe('r.metric({ name: "requests", type: "counter" });');
   });
 });
+
+// Regression guard for the class of bug the r.exposesApi/r.usesApi fold
+// hit: a registrar-shape change (there, removing a method; here, adding a
+// nested optional field) must survive the Designer's parse→render→parse
+// cycle, not just a TS compile of the framework itself. r.screen()'s `nav`
+// sugar is a generic nested object on an already-generic pattern (no
+// per-field extractor/renderer), so this is the cheap case — but proving
+// it beats assuming it.
+const SCREEN_WITH_NAV_FEATURE = `
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+defineFeature("shop", (r) => {
+  r.entity("product", { fields: { name: { type: "text" } } });
+  r.screen({
+    id: "products",
+    type: "entityList",
+    entity: "product",
+    columns: ["name"],
+    nav: { label: "shop:nav.products", icon: "box", order: 5 },
+  });
+});
+`;
+
+describe("render → parse roundtrip — r.screen({ nav }) inline sugar", () => {
+  test("nested nav object survives parse → render → parse unchanged", () => {
+    const initial = parse(SCREEN_WITH_NAV_FEATURE);
+    const rendered = renderFeatureFile({
+      featureName: initial.featureName ?? "",
+      patterns: initial.patterns,
+    });
+    const reparsed = parse(rendered);
+    expect(reparsed.patterns.map(stripLocations)).toEqual(initial.patterns.map(stripLocations));
+
+    const screenPattern = reparsed.patterns.find((p) => p.kind === "screen");
+    expect(screenPattern?.kind).toBe("screen");
+    if (screenPattern?.kind === "screen") {
+      expect(screenPattern.definition).toMatchObject({
+        nav: { label: "shop:nav.products", icon: "box", order: 5 },
+      });
+    }
+  });
+});

package/src/engine/feature-ui-extensions.ts

@@ -260,6 +260,27 @@ export function buildUiExtensionsMethods<TName extends string>(
         );
       }
       state.screens[definition.id] = definition;
+      if (definition.nav) {
+        // Sugar for the common "one nav entry pointing at this screen"
+        // case — synthesizes id/screen from the screen's own id. Beyond
+        // label/icon/parent/order, declare a standalone r.nav() instead.
+        if (state.navs[definition.id]) {
+          throw new Error(
+            `[Feature ${name}] Nav entry "${definition.id}" already registered. ` +
+              `Nav ids must be unique per feature — remove the standalone ` +
+              `r.nav("${definition.id}", ...) call or the screen's inline nav.`,
+          );
+        }
+        const navDefinition: NavDefinition = {
+          id: definition.id,
+          label: definition.nav.label,
+          icon: definition.nav.icon,
+          parent: definition.nav.parent,
+          order: definition.nav.order,
+          screen: `${name}:screen:${definition.id}`,
+        };
+        state.navs[definition.id] = navDefinition;
+      }
     },
     nav(definition: NavDefinition): void {
       // Reject kebab-drift at registration-time so the stack trace points at

package/src/engine/types/feature.ts

@@ -684,7 +684,9 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   // the registry qualifies to "<feature>:screen:<id>". Boot-validation checks
   // that entity-bound screens reference a registered entity and that the
   // columns / form-field refs name real fields — cross-feature component-QN
-  // validation (r.uiComponent) comes in M4/M5.
+  // validation (r.uiComponent) comes in M4/M5. Optional `nav` field is
+  // sugar for a single nav entry pointing at this screen — equivalent to
+  // a standalone r.nav({ id: <same id>, screen: "<feature>:screen:<id>", ... }).
   screen(definition: ScreenDefinition): void;
 
   // Register a nav entry. The id is the feature-local short name (kebab-case);

package/src/engine/types/screen.ts

@@ -727,7 +727,19 @@ export type ScreenSlots = {
 
 // --- discriminated union ---
 
-export type ScreenDefinition =
+// Inline nav-entry sugar for `r.screen({ ..., nav: {...} })` — covers the
+// common case of "one nav entry pointing at this screen". The nav entry's
+// `id`/`screen` are synthesized from the screen's own id; for anything
+// beyond label/icon/parent/order (access-gating, workspaces, actions),
+// declare a standalone `r.nav()` entry instead.
+export type ScreenNavSugar = {
+  readonly label: string;
+  readonly icon?: string;
+  readonly parent?: string;
+  readonly order?: number;
+};
+
+export type ScreenDefinition = (
   | EntityListScreenDefinition
   | ProjectionListScreenDefinition
   | ProjectionDetailScreenDefinition
@@ -735,7 +747,8 @@ export type ScreenDefinition =
   | EntityEditScreenDefinition
   | ActionFormScreenDefinition
   | ConfigEditScreenDefinition
-  | CustomScreenDefinition;
+  | CustomScreenDefinition
+) & { readonly nav?: ScreenNavSugar };
 
 // Type guard — narrows FieldRenderer to FormatSpec. Useful for renderer
 // authors who branch on the three FieldRenderer variants without manual