@cosmicdrift/kumiko-framework 0.410.0 → 0.411.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. package/agents/api/framework-engine.md +2 -0
  2. package/agents/api/framework-ui-types.md +10 -0
  3. package/agents/api/renderer-web.md +113 -10
  4. package/agents/api/types.md +22 -0
  5. package/agents/api.md +1 -1
  6. package/agents/boot-rules.md +4 -0
  7. package/agents/examples/realtime-sse.md +37 -2
  8. package/agents/examples/record-detail-layout.md +35 -2
  9. package/agents/examples/wizard-form.md +96 -5
  10. package/agents/features.md +6 -0
  11. package/agents/widgets.md +6 -0
  12. package/dist/db/queries/session-advisory-lock.js +3 -0
  13. package/dist/engine/boot-validator/boot-rules.d.ts +20 -0
  14. package/dist/engine/boot-validator/list-table-options.js +1 -0
  15. package/dist/engine/boot-validator/screens-forms-layout-rules.d.ts +15 -0
  16. package/dist/engine/boot-validator/screens-forms-layout-rules.js +15 -0
  17. package/dist/engine/boot-validator/screens-forms.d.ts +1 -1
  18. package/dist/engine/boot-validator/screens-forms.js +60 -3
  19. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +5 -0
  20. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +5 -0
  21. package/dist/engine/boot-validator/screens-kind-projection-detail.js +19 -0
  22. package/dist/engine/boot-validator/screens-lists.js +2 -2
  23. package/dist/engine/project-app-schema-for-roles.js +11 -10
  24. package/dist/engine/screen-helpers.d.ts +1 -0
  25. package/dist/engine/screen-helpers.js +1 -1
  26. package/dist/pipeline/context-services.d.ts +1 -0
  27. package/dist/pipeline/context-services.js +1 -0
  28. package/dist/pipeline/handler-context-scope.js +5 -1
  29. package/dist/pipeline/user-live-signals.d.ts +5 -0
  30. package/dist/pipeline/user-live-signals.js +20 -0
  31. package/package.json +3 -3
  32. package/src/changes.json +48 -0
@@ -32,6 +32,15 @@ the user left off.
32
32
  mounted alongside this one (both enforced at boot). The actual
33
33
  save/resume/discard wiring happens automatically inside `RenderEdit` —
34
34
  this recipe never calls a form-draft handler from its own code.
35
+ - **Step rail texts** — a section's `subtitle` is the line under its step in
36
+ the rail (opt-in, `description` is never used there); `summaryField`
37
+ replaces it with the entered value once the step is done. `wizard.aside`
38
+ adds the "up next" card, and `finishDescription` the finish card on the
39
+ last step. Extension steps take the same three texts; on an `actionForm`
40
+ `summaryField` and `submitDisabledWhen` may name a field of its `fields`.
41
+ - **Footer options** — `wizard.saveAndCloseOnCreate` offers "Save and close" (also on the last step)
42
+ while creating; `wizard.submitDisabledWhen` disables Finish while a field
43
+ condition holds. It is UI-only: enforce the rule in a validation hook too.
35
44
 
36
45
  ## Feature composition
37
46
 
@@ -881,12 +890,15 @@ test.describe("wizard-form — step navigation, validation, draft resume", () =>
881
890
  const rail = page.getByTestId("render-edit-wizard-steps");
882
891
  const step0 = page.getByTestId("render-edit-wizard-steps-step-0");
883
892
  const step1 = page.getByTestId("render-edit-wizard-steps-step-1");
893
+ const step2 = page.getByTestId("render-edit-wizard-steps-step-2");
884
894
 
885
895
  await expect(rail).toBeVisible();
886
896
  await expect(page.getByTestId("render-edit-wizard-progress")).toHaveCount(0);
887
897
  await expect(step0).toHaveAttribute("aria-current", "step");
888
- await expect(step0).toHaveCSS("height", "36px");
889
- await expect(step1).toHaveCSS("height", "36px");
898
+ // Rows with a subtitle grow past 36px; the subtitle-less Review row pins the exact box.
899
+ await expect(step2).toHaveCSS("height", "36px");
900
+ expect((await step0.boundingBox())?.height).toBeGreaterThanOrEqual(36);
901
+ expect((await step1.boundingBox())?.height).toBeGreaterThanOrEqual(36);
890
902
 
891
903
  await page.getByTestId("field-title").locator("input").fill("Vintage desk lamp");
892
904
  await selectCombobox(page, "category", "furniture");
@@ -894,7 +906,75 @@ test.describe("wizard-form — step navigation, validation, draft resume", () =>
894
906
 
895
907
  await expect(step1).toHaveAttribute("aria-current", "step");
896
908
  await expect(step0).not.toHaveAttribute("aria-current", "step");
897
- await expect(step1).toHaveCSS("height", "36px");
909
+ await expect(step2).toHaveCSS("height", "36px");
910
+ });
911
+
912
+ test("the rail shows the other steps' subtitles and, once a step is done, its summaryField value", async ({
913
+ page,
914
+ }) => {
915
+ await gotoWizard(page);
916
+ await expect(page.getByTestId("render-edit-wizard-steps-subtitle-0")).toHaveCount(0);
917
+ await expect(page.getByTestId("render-edit-wizard-steps-subtitle-1")).toHaveText(
918
+ "Price and condition",
919
+ );
920
+
921
+ await page.getByTestId("field-title").locator("input").fill("Vintage desk lamp");
922
+ await selectCombobox(page, "category", "furniture");
923
+ await page.getByTestId("render-edit-wizard-next").click();
924
+
925
+ await expect(page.getByTestId("render-edit-wizard-steps-subtitle-0")).toHaveText(
926
+ "Vintage desk lamp",
927
+ );
928
+ await expect(page.getByTestId("render-edit-wizard-steps-subtitle-1")).toHaveCount(0);
929
+ });
930
+
931
+ test("the up-next card names the next step and, on the last step, the finish action", async ({
932
+ page,
933
+ }) => {
934
+ await gotoWizard(page);
935
+ const upNext = page.getByTestId("render-edit-wizard-steps-up-next");
936
+ await expect(upNext).toContainText("Pricing");
937
+ await expect(upNext).toContainText("Price and condition");
938
+
939
+ await page.getByTestId("field-title").locator("input").fill("Vintage desk lamp");
940
+ await selectCombobox(page, "category", "furniture");
941
+ await page.getByTestId("render-edit-wizard-next").click();
942
+ await expect(upNext).toContainText("Review");
943
+ await page.getByTestId("field-price").locator("input").fill("42");
944
+ await page.getByTestId("render-edit-wizard-next").click();
945
+
946
+ await expect(upNext).toContainText("Publishes the listing.");
947
+ });
948
+
949
+ test("Save and close is offered while creating and creates the listing", async ({ page }) => {
950
+ await gotoWizard(page);
951
+ await page.getByTestId("field-title").locator("input").fill("Quick save lamp");
952
+ await selectCombobox(page, "category", "furniture");
953
+
954
+ await page.getByTestId("render-edit-wizard-save-close").click();
955
+
956
+ await expect
957
+ .poll(async () => (await createdListings(page)).map((listing) => listing["title"]))
958
+ .toEqual(["Quick save lamp"]);
959
+ });
960
+
961
+ test("submitDisabledWhen disables Finish while the category is vehicles", async ({ page }) => {
962
+ await gotoWizard(page);
963
+ await page.getByTestId("field-title").locator("input").fill("Old bicycle");
964
+ await selectCombobox(page, "category", "vehicles");
965
+ await page.getByTestId("render-edit-wizard-next").click();
966
+ await page.getByTestId("field-price").locator("input").fill("150");
967
+ await page.getByTestId("render-edit-wizard-next").click();
968
+
969
+ await expect(page.getByTestId("render-edit-submit")).toBeDisabled();
970
+
971
+ await page.getByTestId("render-edit-wizard-back").click();
972
+ await page.getByTestId("render-edit-wizard-back").click();
973
+ await selectCombobox(page, "category", "furniture");
974
+ await page.getByTestId("render-edit-wizard-next").click();
975
+ await page.getByTestId("render-edit-wizard-next").click();
976
+
977
+ await expect(page.getByTestId("render-edit-submit")).toBeEnabled();
898
978
  });
899
979
 
900
980
  test("an empty required field blocks Next and shows a field error", async ({ page }) => {
@@ -1256,9 +1336,20 @@ export const listingsFeature = defineFeature("listings", (r) => {
1256
1336
  layout: {
1257
1337
  mode: "wizard",
1258
1338
  draft: true,
1339
+ wizard: {
1340
+ aside: { upNext: true, finishDescription: "Publishes the listing." },
1341
+ saveAndCloseOnCreate: true,
1342
+ // UI-only: the write handler would still accept a vehicle listing.
1343
+ submitDisabledWhen: { field: "category", eq: "vehicles" },
1344
+ },
1259
1345
  sections: [
1260
- { title: "Basics", fields: ["title", "category"] },
1261
- { title: "Pricing", fields: ["price", "condition"] },
1346
+ {
1347
+ title: "Basics",
1348
+ subtitle: "Title and category",
1349
+ summaryField: "title",
1350
+ fields: ["title", "category"],
1351
+ },
1352
+ { title: "Pricing", subtitle: "Price and condition", fields: ["price", "condition"] },
1262
1353
  {
1263
1354
  kind: "extension",
1264
1355
  title: "Review",
@@ -558,6 +558,12 @@ Category: identity
558
558
 
559
559
  Requires: `user`, `tenant`, `auth-foundation`
560
560
 
561
+ ## presence
562
+
563
+ Who else is on this record right now: a browser sends a heartbeat every 15 seconds for one row of an allow-listed entity and gets the other viewers and editors back, with a live signal to them on a change. State is ephemeral (Redis hash per tenant, entity and row, in-memory without Redis), keyed by the session tenant, expires after ttlSeconds without a heartbeat and holds user ids only; display names are looked up per response. A caller sees presence only for rows visible to them. Mount with createPresenceFeature({ entities: ["task"] }).
564
+
565
+ Category: communication
566
+
561
567
  ## rate-limiting
562
568
 
563
569
  Adds an ops-side `rate-limiting:query:status` query handler for inspecting current bucket state; the actual request throttling is wired automatically by the dispatcher when any handler declares a `rateLimit` option (e.g. `{ per: 'user', limit: 3, windowSeconds: 60 }`) or when you pass `context.rateLimit` to `buildServer`. Loading this feature is optional if you only need L3 per-handler rate limits and have no need for ops introspection.
package/agents/widgets.md CHANGED
@@ -23,6 +23,7 @@ Value exports of `@cosmicdrift/kumiko-renderer/web`.
23
23
  | `ClampedText` | Clamps content to `lines`; the toggle shows only while the content actually overflows. |
24
24
  | `CollapsibleSection` | Collapsible section using native <details> with React-controlled state; otherwise the open attribute resets to its initial value on every parent re-render. |
25
25
  | `ComparisonTable` | Transposed comparison table: row = metric, column = variant, with the best column optionally highlighted for each metric. |
26
+ | `Composer` | Chat input: a label-less textarea with a text send button inside the field frame, bottom right. |
26
27
  | `DateField` | Date field = Field + Input(kind:"date"), ISO yyyy-mm-dd. |
27
28
  | `DefaultAppShell` | |
28
29
  | `DetailList` | Read-only key-value list for detail views (dimmed label on the left, value on the right). |
@@ -69,6 +70,8 @@ Value exports of `@cosmicdrift/kumiko-renderer/web`.
69
70
  | `PlainContentEditor` | |
70
71
  | `PlanCard` | |
71
72
  | `PlanGrid` | |
73
+ | `PresenceAvatars` | Small round avatars of the people on a row, with "+n" for the rest; for list rows. |
74
+ | `PresenceNotice` | One quiet line above a record: who else is on it and for how long. |
72
75
  | `PrimitivesProvider` | |
73
76
  | `ProfileMenu` | |
74
77
  | `ProgressBar` | Progress bar, `value` 0..1 (clamped). |
@@ -86,6 +89,7 @@ Value exports of `@cosmicdrift/kumiko-renderer/web`.
86
89
  | `ResultTable` | Static, prop-driven result table for calculated rows (tranches, scenarios). |
87
90
  | `ScreenWidthProvider` | |
88
91
  | `SectionCard` | Section with a title and optional action slot (range switcher, filter) — replaces repeated `<section className={CARD}>…<h2>` blocks in custom screens. |
92
+ | `SectionNavLayout` | Content column plus an "On this page" navigation in a right column (from xl), for custom screens. |
89
93
  | `SelectField` | Select field = Field + Input(kind:"select"). |
90
94
  | `SenderFrame` | Sand frame with one white sheet inside, for content that mimics a letter or mail. |
91
95
  | `SenderSheet` | The white sheet alone, for a frame that holds several sheets (PDF pages, thumbnails). |
@@ -134,6 +138,8 @@ Value exports of `@cosmicdrift/kumiko-renderer/web`.
134
138
  | `useLiveEvents` | Hook for a useQuery-like consumer. |
135
139
  | `useLocale` | Provides the current LocaleResolver and automatically subscribes to locale changes — the calling component re-renders when the language changes. |
136
140
  | `useNav` | |
141
+ | `usePresence` | Announces the user on one record: a heartbeat right away and every 15 s, a leave when the record closes. |
142
+ | `usePresenceList` | Who else is on each of the given rows, for badges in a list. |
137
143
  | `usePrimitives` | |
138
144
  | `useQuery` | |
139
145
  | `useResolvers` | |
@@ -8,6 +8,8 @@ export async function withSessionAdvisoryLock(db, key, fn) {
8
8
  }
9
9
  const conn = await client.reserve();
10
10
  try {
11
+ // Waiting for a peer must not hit the pool's statement_timeout (57014 would crash the waiter's boot).
12
+ await conn.unsafe("SET statement_timeout = 0");
11
13
  await conn.unsafe(`SELECT pg_advisory_lock($1)`, [key]);
12
14
  try {
13
15
  return await fn();
@@ -15,6 +17,7 @@ export async function withSessionAdvisoryLock(db, key, fn) {
15
17
  finally {
16
18
  // A dropped session already released its lock; failing here would mask fn's outcome.
17
19
  await conn.unsafe(`SELECT pg_advisory_unlock($1)`, [key]).catch(() => undefined);
20
+ await conn.unsafe("RESET statement_timeout").catch(() => undefined);
18
21
  }
19
22
  }
20
23
  finally {
@@ -957,6 +957,21 @@ export declare const FRAMEWORK_BOOT_RULE_TABLES: readonly [{
957
957
  readonly summary: "Every wizard section has a non-empty title.";
958
958
  readonly fix: "Give each wizard section a title.";
959
959
  };
960
+ readonly wizardOptionWithoutWizard: {
961
+ readonly id: "form/wizard-option-without-wizard";
962
+ readonly summary: "layout.wizard.saveAndCloseOnCreate, submitDisabledWhen, aside.finishDescription and section summaryField are set only on a wizard layout.";
963
+ readonly fix: 'Remove the option or set mode: "wizard".';
964
+ };
965
+ readonly wizardSummaryFieldUnknown: {
966
+ readonly id: "form/wizard-summary-field-unknown";
967
+ readonly summary: "A wizard section summaryField names a field of that section.";
968
+ readonly fix: "Use a field name declared in the section.";
969
+ };
970
+ readonly wizardSubmitConditionFieldUnknown: {
971
+ readonly id: "form/wizard-submit-condition-field-unknown";
972
+ readonly summary: "layout.wizard.submitDisabledWhen names a field of the layout.";
973
+ readonly fix: "Use a field name declared in one of the sections.";
974
+ };
960
975
  readonly sectionFieldsAndGroups: {
961
976
  readonly id: "form/section-fields-and-groups";
962
977
  readonly summary: "A section declares fields or groups, not both.";
@@ -1270,6 +1285,11 @@ export declare const FRAMEWORK_BOOT_RULE_TABLES: readonly [{
1270
1285
  readonly summary: "A metric navigate.tab names a section id of the screen.";
1271
1286
  readonly fix: "Navigate to an existing section id or remove navigate.tab.";
1272
1287
  };
1288
+ readonly actionShowOnTabsInvalid: {
1289
+ readonly id: "projection-detail/action-show-on-tabs-invalid";
1290
+ readonly summary: 'A header action showOnTabs is non-empty, names section ids of the screen and needs layout.mode "tabs".';
1291
+ readonly fix: "List existing section ids or remove showOnTabs.";
1292
+ };
1273
1293
  readonly metricLabelMissing: {
1274
1294
  readonly id: "projection-detail/metric-label-missing";
1275
1295
  readonly summary: "Every metric has an i18n label key.";
@@ -14,6 +14,7 @@ const BOOLEAN_OPTION_KEYS = [
14
14
  "pinning",
15
15
  "resizing",
16
16
  "keyboardNavigation",
17
+ "compactHeader",
17
18
  ];
18
19
  function validateDensity(where, density) {
19
20
  if (!isPlainObject(density)) {
@@ -49,6 +49,21 @@ export declare const FORM_LAYOUT_RULES: {
49
49
  readonly summary: "Every wizard section has a non-empty title.";
50
50
  readonly fix: "Give each wizard section a title.";
51
51
  };
52
+ readonly wizardOptionWithoutWizard: {
53
+ readonly id: "form/wizard-option-without-wizard";
54
+ readonly summary: "layout.wizard.saveAndCloseOnCreate, submitDisabledWhen, aside.finishDescription and section summaryField are set only on a wizard layout.";
55
+ readonly fix: 'Remove the option or set mode: "wizard".';
56
+ };
57
+ readonly wizardSummaryFieldUnknown: {
58
+ readonly id: "form/wizard-summary-field-unknown";
59
+ readonly summary: "A wizard section summaryField names a field of that section.";
60
+ readonly fix: "Use a field name declared in the section.";
61
+ };
62
+ readonly wizardSubmitConditionFieldUnknown: {
63
+ readonly id: "form/wizard-submit-condition-field-unknown";
64
+ readonly summary: "layout.wizard.submitDisabledWhen names a field of the layout.";
65
+ readonly fix: "Use a field name declared in one of the sections.";
66
+ };
52
67
  readonly sectionFieldsAndGroups: {
53
68
  readonly id: "form/section-fields-and-groups";
54
69
  readonly summary: "A section declares fields or groups, not both.";
@@ -49,6 +49,21 @@ export const FORM_LAYOUT_RULES = {
49
49
  summary: "Every wizard section has a non-empty title.",
50
50
  fix: "Give each wizard section a title.",
51
51
  },
52
+ wizardOptionWithoutWizard: {
53
+ id: "form/wizard-option-without-wizard",
54
+ summary: "layout.wizard.saveAndCloseOnCreate, submitDisabledWhen, aside.finishDescription and section summaryField are set only on a wizard layout.",
55
+ fix: 'Remove the option or set mode: "wizard".',
56
+ },
57
+ wizardSummaryFieldUnknown: {
58
+ id: "form/wizard-summary-field-unknown",
59
+ summary: "A wizard section summaryField names a field of that section.",
60
+ fix: "Use a field name declared in the section.",
61
+ },
62
+ wizardSubmitConditionFieldUnknown: {
63
+ id: "form/wizard-submit-condition-field-unknown",
64
+ summary: "layout.wizard.submitDisabledWhen names a field of the layout.",
65
+ fix: "Use a field name declared in one of the sections.",
66
+ },
52
67
  sectionFieldsAndGroups: {
53
68
  id: "form/section-fields-and-groups",
54
69
  summary: "A section declares fields or groups, not both.",
@@ -13,7 +13,7 @@ export declare function validateTabSections(featureName: string, screenId: strin
13
13
  readonly id?: string;
14
14
  readonly title?: string;
15
15
  }[]): void;
16
- export declare function validateWizardLayout(featureName: string, screenId: string, screenType: "entityEdit" | "actionForm" | "configEdit" | "secretMint", layout: EditLayout, featureMap: ReadonlyMap<string, FeatureDefinition>): void;
16
+ export declare function validateWizardLayout(featureName: string, screenId: string, screenType: "entityEdit" | "actionForm" | "configEdit" | "secretMint", layout: EditLayout, featureMap: ReadonlyMap<string, FeatureDefinition>, inlineFieldNames?: ReadonlySet<string>): void;
17
17
  export declare function isWriteOnlyField(fdef: FieldDefinition | undefined): boolean;
18
18
  export declare function validateConfigEditSecretField(featureName: string, screen: ConfigEditScreenDefinition, fieldName: string, secretQn: string, featureMap: ReadonlyMap<string, FeatureDefinition>): void;
19
19
  export declare function rejectWriteOnlyFormField(featureName: string, screenId: string, context: string, fieldName: string, fdef: FieldDefinition): void;
@@ -1,6 +1,6 @@
1
1
  import { NO_WIDGET_FIELD_TYPES, optionsQueryFieldRefs } from "@cosmicdrift/kumiko-types/fields";
2
2
  import { isKebabSegment } from "../qualified-name.js";
3
- import { isExtensionEditSection, isWriteFormEditSection, normalizeEditField, sectionFieldSpecs, } from "../screen-helpers.js";
3
+ import { isExtensionEditSection, isFieldsEditSection, isWriteFormEditSection, normalizeEditField, sectionFieldSpecs, } from "../screen-helpers.js";
4
4
  import { bootRuleError } from "./boot-rule.js";
5
5
  import { validateFormDerivations, validateFormDerivationsEnforced } from "./form-derivations.js";
6
6
  import { assertWriteHandlerRegistered, isSensitiveOrPasswordField, validateIdlessSuccessLink, validateRedirectTarget, validateScreenNavTarget, } from "./screens-actions.js";
@@ -189,10 +189,66 @@ export function validateTabSections(featureName, screenId, screenType, sections)
189
189
  tabIds.add(section.id);
190
190
  });
191
191
  }
192
+ // An actionForm's own `fields` count too: extension steps (a wizard with no fields section) keep their values there.
193
+ function wizardFieldNames(layout, inlineFieldNames) {
194
+ const names = new Set(inlineFieldNames);
195
+ for (const section of layout.sections) {
196
+ if (!isFieldsEditSection(section))
197
+ continue;
198
+ for (const spec of sectionFieldSpecs(section))
199
+ names.add(normalizeEditField(spec).field);
200
+ }
201
+ return names;
202
+ }
203
+ function usesWizardOption(layout) {
204
+ const wizard = layout.wizard;
205
+ return (wizard?.saveAndCloseOnCreate !== undefined ||
206
+ wizard?.submitDisabledWhen !== undefined ||
207
+ wizard?.aside?.finishDescription !== undefined ||
208
+ layout.sections.some((section) => (isFieldsEditSection(section) || section.kind === "extension") &&
209
+ section.summaryField !== undefined));
210
+ }
211
+ function validateWizardOptions(featureName, screenId, screenType, layout, inlineFieldNames) {
212
+ const where = `[Feature ${featureName}] Screen "${screenId}" (${screenType})`;
213
+ const wizard = layout.wizard;
214
+ if (layout.mode !== "wizard") {
215
+ if (usesWizardOption(layout)) {
216
+ throw bootRuleError(FORM_LAYOUT_RULES.wizardOptionWithoutWizard, {
217
+ message: `${where} sets a wizard-only layout option but mode is not "wizard". Remove it or set mode: "wizard".`,
218
+ });
219
+ }
220
+ // skip: the remaining checks only apply to wizards
221
+ return;
222
+ }
223
+ const allFieldNames = wizardFieldNames(layout, inlineFieldNames);
224
+ for (const section of layout.sections) {
225
+ if (section.kind === "extension" &&
226
+ section.summaryField !== undefined &&
227
+ !allFieldNames.has(section.summaryField)) {
228
+ throw bootRuleError(FORM_LAYOUT_RULES.wizardSummaryFieldUnknown, {
229
+ message: `${where} extension section "${section.title}" sets summaryField "${section.summaryField}", which is not a field of the screen. Use a field name declared in the screen's fields or a fields section.`,
230
+ });
231
+ }
232
+ if (!isFieldsEditSection(section))
233
+ continue;
234
+ const sectionFieldNames = sectionFieldSpecs(section).map((spec) => normalizeEditField(spec).field);
235
+ if (section.summaryField !== undefined && !sectionFieldNames.includes(section.summaryField)) {
236
+ throw bootRuleError(FORM_LAYOUT_RULES.wizardSummaryFieldUnknown, {
237
+ message: `${where} section "${section.title ?? ""}" sets summaryField "${section.summaryField}", which is not a field of that section. Use a field name declared in the section.`,
238
+ });
239
+ }
240
+ }
241
+ const condition = wizard?.submitDisabledWhen;
242
+ if (typeof condition === "object" && !allFieldNames.has(condition.field)) {
243
+ throw bootRuleError(FORM_LAYOUT_RULES.wizardSubmitConditionFieldUnknown, {
244
+ message: `${where} layout.wizard.submitDisabledWhen names field "${condition.field}", which no section declares. Use a field name declared in one of the sections.`,
245
+ });
246
+ }
247
+ }
192
248
  // Wizard layouts (mode: "wizard") need >= 2 titled sections — a single or
193
249
  // untitled step would leave the progress indicator blank, so both fail at
194
250
  // boot rather than as a broken step UI.
195
- export function validateWizardLayout(featureName, screenId, screenType, layout, featureMap) {
251
+ export function validateWizardLayout(featureName, screenId, screenType, layout, featureMap, inlineFieldNames) {
196
252
  // entityEdit renders tabs like wizard steps: every section stays mounted,
197
253
  // submit validates across all of them, and a field error jumps to the tab
198
254
  // holding it. The other three have no such jump — actionForm and
@@ -227,6 +283,7 @@ export function validateWizardLayout(featureName, screenId, screenType, layout,
227
283
  });
228
284
  }
229
285
  }
286
+ validateWizardOptions(featureName, screenId, screenType, layout, inlineFieldNames);
230
287
  // skip: mode omitted/"single" — no wizard constraints apply.
231
288
  if (layout.mode !== "wizard")
232
289
  return;
@@ -584,7 +641,7 @@ export function validateInlineFormScreen(feature, screenId, screen, kind, allWri
584
641
  const allowEmptyMintForm = kind === "secretMint";
585
642
  const fieldNames = validateFormFieldsMap(feature.name, screenId, kind, screen.fields, allowEmptyMintForm);
586
643
  validateFormLayoutSections(feature.name, screenId, kind, screen.layout, fieldNames, screen.fields, allowEmptyMintForm && fieldNames.size === 0);
587
- validateWizardLayout(feature.name, screenId, kind, screen.layout, featureMap);
644
+ validateWizardLayout(feature.name, screenId, kind, screen.layout, featureMap, fieldNames);
588
645
  if (screen.type === "actionForm") {
589
646
  validateFormDerivations(feature.name, screenId, screen);
590
647
  validateFormDerivationsEnforced(feature.name, screenId, screen, featureMap);
@@ -24,6 +24,11 @@ export declare const PROJECTION_DETAIL_RULES: {
24
24
  readonly summary: "A metric navigate.tab names a section id of the screen.";
25
25
  readonly fix: "Navigate to an existing section id or remove navigate.tab.";
26
26
  };
27
+ readonly actionShowOnTabsInvalid: {
28
+ readonly id: "projection-detail/action-show-on-tabs-invalid";
29
+ readonly summary: 'A header action showOnTabs is non-empty, names section ids of the screen and needs layout.mode "tabs".';
30
+ readonly fix: "List existing section ids or remove showOnTabs.";
31
+ };
27
32
  readonly metricLabelMissing: {
28
33
  readonly id: "projection-detail/metric-label-missing";
29
34
  readonly summary: "Every metric has an i18n label key.";
@@ -24,6 +24,11 @@ export const PROJECTION_DETAIL_RULES = {
24
24
  summary: "A metric navigate.tab names a section id of the screen.",
25
25
  fix: "Navigate to an existing section id or remove navigate.tab.",
26
26
  },
27
+ actionShowOnTabsInvalid: {
28
+ id: "projection-detail/action-show-on-tabs-invalid",
29
+ summary: 'A header action showOnTabs is non-empty, names section ids of the screen and needs layout.mode "tabs".',
30
+ fix: "List existing section ids or remove showOnTabs.",
31
+ },
27
32
  metricLabelMissing: {
28
33
  id: "projection-detail/metric-label-missing",
29
34
  summary: "Every metric has an i18n label key.",
@@ -255,6 +255,24 @@ function validateProjectionDetailSection(ctx, screenId, screen, section) {
255
255
  validateProjectionDetailFieldsSection(ctx, screenId, section);
256
256
  }
257
257
  }
258
+ function validateHeaderActionShowOnTabs(featureName, screenId, screen, action) {
259
+ // skip: no showOnTabs declared, the action is shown on every tab
260
+ if (action.showOnTabs === undefined)
261
+ return;
262
+ const sectionIds = screen.layout.sections.map((section) => section.id);
263
+ const unknownTab = action.showOnTabs.find((tab) => !sectionIds.includes(tab));
264
+ if (screen.layout.mode !== "tabs" || action.showOnTabs.length === 0 || unknownTab !== undefined) {
265
+ throw bootRuleError(PROJECTION_DETAIL_RULES.actionShowOnTabsInvalid, {
266
+ message: `[Feature ${featureName}] Screen "${screenId}" (projectionDetail) action "${action.id}" ` +
267
+ `sets showOnTabs ${JSON.stringify(action.showOnTabs)}` +
268
+ (unknownTab !== undefined
269
+ ? `, but "${unknownTab}" is not a section id on this screen`
270
+ : "") +
271
+ (screen.layout.mode !== "tabs" ? ` — showOnTabs needs layout.mode "tabs"` : "") +
272
+ `. List existing section ids (at least one) or remove showOnTabs.`,
273
+ });
274
+ }
275
+ }
258
276
  // Query-driven like projectionList, but a single row plus layout instead of
259
277
  // columns. No entity check is possible: fields resolve against the query
260
278
  // response at render time, not against an entity.
@@ -277,5 +295,6 @@ export function validateProjectionDetailScreen(ctx, screenId, screen) {
277
295
  for (const action of screen.actions ?? []) {
278
296
  validateActionHasIcon(featureName, screenId, "projectionDetail", "action", action);
279
297
  validateRecordHeaderAction(ctx, screenId, "projectionDetail", screen.detailFor, action);
298
+ validateHeaderActionShowOnTabs(featureName, screenId, screen, action);
280
299
  }
281
300
  }
@@ -3,7 +3,7 @@ import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
3
3
  import { REFERENCE_LOOKUP_SOURCES } from "../../ui-types/list-row-meta.js";
4
4
  import { parseRefTarget } from "../parse-ref-target.js";
5
5
  import { qualifyEntityName } from "../qualified-name.js";
6
- import { explicitListScreenId, normalizeListColumn, resolveNavParentScreen, } from "../screen-helpers.js";
6
+ import { explicitListScreenId, normalizeListColumn, resolveNavParentScreen, screenShortId, } from "../screen-helpers.js";
7
7
  import { bootRuleError } from "./boot-rule.js";
8
8
  import { ENTITY_LIST_RULES } from "./entity-list-screens-rules.js";
9
9
  import { validateListBulkActions } from "./list-bulk-actions.js";
@@ -46,7 +46,7 @@ export function validateExplicitListScreenExists(featureName, screenId, screen,
46
46
  // skip: no explicit listScreenId, the nav heuristic applies and there is nothing to validate
47
47
  if (listScreenId === undefined)
48
48
  return;
49
- const shortId = listScreenId.slice(listScreenId.lastIndexOf(":") + 1);
49
+ const shortId = screenShortId(listScreenId);
50
50
  // skip: the explicit listScreenId resolves to a mounted screen
51
51
  if (screensByShortId.has(shortId))
52
52
  return;
@@ -231,15 +231,18 @@ function isTargetKept(target, keptScreenQns) {
231
231
  return false;
232
232
  return keptScreenQns.has(qualifyEntityName(target.featureName, "screen", target.screen.id));
233
233
  }
234
- function resolveNavigateTarget(action, indices) {
235
- if (action.entity !== undefined)
236
- return indices.detailForScreens.get(action.entity);
237
- if (action.screen !== undefined)
238
- return indices.screensByShortId.get(action.screen);
239
- return undefined;
234
+ // A QN names exactly one screen; resolving it through the short-id index could land on another
235
+ // feature's same-named screen and keep a reference to a hidden one.
236
+ function isScreenRefKept(ref, indices, keptScreenQns) {
237
+ if (isValidQn(ref))
238
+ return keptScreenQns.has(ref);
239
+ return isTargetKept(indices.screensByShortId.get(ref), keptScreenQns);
240
240
  }
241
241
  function isNavigateTargetKept(action, indices, keptScreenQns) {
242
- const target = resolveNavigateTarget(action, indices);
242
+ if (action.entity === undefined && action.screen !== undefined) {
243
+ return isScreenRefKept(action.screen, indices, keptScreenQns);
244
+ }
245
+ const target = action.entity === undefined ? undefined : indices.detailForScreens.get(action.entity);
243
246
  if (target === undefined)
244
247
  return false;
245
248
  return keptScreenQns.has(qualifyEntityName(target.featureName, "screen", target.screen.id));
@@ -404,9 +407,7 @@ function projectDashboardPanels(panels, feature, keptScreenQns) {
404
407
  function projectListScreenId(listScreenId, indices, keptScreenQns) {
405
408
  if (listScreenId === undefined)
406
409
  return undefined;
407
- return isTargetKept(indices.screensByShortId.get(listScreenId), keptScreenQns)
408
- ? listScreenId
409
- : undefined;
410
+ return isScreenRefKept(listScreenId, indices, keptScreenQns) ? listScreenId : undefined;
410
411
  }
411
412
  // guard:dup-ok sibling of projectListScreenId for a different reference kind with its own keep check
412
413
  function projectRedirect(featureName, redirect, keptScreenQns) {
@@ -2,6 +2,7 @@ import type { FieldDefinition, SelectFieldDef } from "./types/fields.ts";
2
2
  import type { ActionFormScreenDefinition, ConfigEditScreenDefinition, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditSectionSpec, EditWriteFormSection, EntityEditScreenDefinition, FieldCondition, FormatSpec, ListColumnSpec, ProjectionDetailScreenDefinition, ScreenDefinition, SecretMintScreenDefinition } from "./types/screen.ts";
3
3
  export declare const ACTION_FORM_PSEUDO_ENTITY = "__action-form__";
4
4
  export declare function explicitListScreenId(screen: ScreenDefinition): string | undefined;
5
+ export declare function screenShortId(ref: string): string;
5
6
  export declare function resolveNavParentScreen(screens: readonly ScreenDefinition[], detail: ScreenDefinition, getId: (screen: ScreenDefinition) => string): ScreenDefinition | undefined;
6
7
  export type EditLayoutScreen = ProjectionDetailScreenDefinition | EntityEditScreenDefinition | ActionFormScreenDefinition | ConfigEditScreenDefinition | SecretMintScreenDefinition;
7
8
  export declare function isEditLayoutScreen(screen: ScreenDefinition): screen is EditLayoutScreen;
@@ -19,7 +19,7 @@ export function explicitListScreenId(screen) {
19
19
  }
20
20
  // Screen refs may be short ids or `<feature>:screen:<id>` QNs (boot-validator
21
21
  // accepts both for navigate targets and listScreenId); compare on the short id.
22
- function screenShortId(ref) {
22
+ export function screenShortId(ref) {
23
23
  return ref.slice(ref.lastIndexOf(":") + 1);
24
24
  }
25
25
  // Shared by the renderer breadcrumb and the boot-validator so both resolve
@@ -3,6 +3,7 @@ type ServiceKey = Exclude<keyof ContextServices, "extensions">;
3
3
  export declare const APP_CONTEXT_KEY_ROLES: {
4
4
  readonly redis: "service";
5
5
  readonly cacheSync: "service";
6
+ readonly userLiveSignals: "service";
6
7
  readonly jobRunner: "service";
7
8
  readonly searchAdapter: "service";
8
9
  readonly entityCache: "service";
@@ -3,6 +3,7 @@
3
3
  export const APP_CONTEXT_KEY_ROLES = {
4
4
  redis: "service",
5
5
  cacheSync: "service",
6
+ userLiveSignals: "service",
6
7
  jobRunner: "service",
7
8
  searchAdapter: "service",
8
9
  entityCache: "service",
@@ -3,6 +3,7 @@ import { requestContext } from "../api/request-context.js";
3
3
  import { createFallbackLogger } from "../logging/utils.js";
4
4
  import { createEscapeHatchReporter } from "../observability/escape-hatch-report.js";
5
5
  import { resolveDbSource, } from "./dispatch-shared.js";
6
+ import { createUserLiveSignals } from "./user-live-signals.js";
6
7
  export function resolveHandlerContextScope(input) {
7
8
  const { ctx, type, user, origin, tx, transactionScope } = input;
8
9
  const { registry, appContext: context } = ctx;
@@ -69,8 +70,11 @@ export function buildPreSave(scope, finalContext) {
69
70
  }
70
71
  // Services the dispatcher resolves itself instead of copying from the boot context.
71
72
  export function buildRuntimeServices(scope) {
72
- const { effectiveFeatures, jobRunner, cacheSync } = scope.ctx;
73
+ const { effectiveFeatures, jobRunner, cacheSync, sseBroker } = scope.ctx;
73
74
  return {
75
+ ...(sseBroker && {
76
+ userLiveSignals: createUserLiveSignals(sseBroker, scope.user.tenantId, scope.context.log ?? createFallbackLogger("dispatcher")),
77
+ }),
74
78
  // One resolver for the lifecycle pipeline, MSP runner and ctx.hasFeature.
75
79
  ...(effectiveFeatures && { effectiveFeatures }),
76
80
  ...(cacheSync && { cacheSync }),
@@ -0,0 +1,5 @@
1
+ import type { UserLiveSignals } from "@cosmicdrift/kumiko-types/handlers";
2
+ import type { TenantId } from "@cosmicdrift/kumiko-types/identifiers";
3
+ import type { SseBroker } from "../api/sse-broker.ts";
4
+ import type { Logger } from "../logging/types.ts";
5
+ export declare function createUserLiveSignals(sseBroker: SseBroker, tenantId: TenantId, log: Pick<Logger, "warn">): UserLiveSignals;
@@ -0,0 +1,20 @@
1
+ import { tenantChannel } from "../engine/constants.js";
2
+ // The tenant is fixed to the caller's own: a handler can address users, never another tenant's channel.
3
+ // Frames carry `data.userId` and no aggregateType, so sse-route delivers each only to its addressee.
4
+ export function createUserLiveSignals(sseBroker, tenantId, log) {
5
+ return {
6
+ async push(userIds, signal) {
7
+ await Promise.all([...new Set(userIds)].map(async (userId) => {
8
+ try {
9
+ await sseBroker.pushToChannel(tenantChannel(tenantId), {
10
+ type: signal.type,
11
+ data: { userId, entity: signal.entity, id: signal.id },
12
+ });
13
+ }
14
+ catch (err) {
15
+ log.warn(`live signal "${signal.type}" could not be pushed`, { err });
16
+ }
17
+ }));
18
+ },
19
+ };
20
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cosmicdrift/kumiko-framework",
3
- "version": "0.410.0",
3
+ "version": "0.411.0",
4
4
  "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
5
5
  "license": "MIT",
6
6
  "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -203,7 +203,7 @@
203
203
  "./package.json": "./package.json"
204
204
  },
205
205
  "dependencies": {
206
- "@cosmicdrift/kumiko-types": "0.410.0",
206
+ "@cosmicdrift/kumiko-types": "0.411.0",
207
207
  "bullmq": "^5.81.5",
208
208
  "hono": "^4.13.14",
209
209
  "i18next": "^26.5.12",
@@ -225,7 +225,7 @@
225
225
  }
226
226
  },
227
227
  "devDependencies": {
228
- "@cosmicdrift/kumiko-testing": "0.410.0",
228
+ "@cosmicdrift/kumiko-testing": "0.411.0",
229
229
  "bun-types": "^1.4.4",
230
230
  "fflate": "^0.8.3",
231
231
  "meilisearch": "^0.62.0",