@cosmicdrift/kumiko-samples 0.351.0 → 0.353.0

package/packages/bundled-features/src/tenant-lifecycle/run-tenant-destroy.ts

@@ -14,6 +14,7 @@ import {
   VersionConflictError,
 } from "@cosmicdrift/kumiko-framework/event-store";
 import type { FileProviderResolver } from "@cosmicdrift/kumiko-framework/files";
+import type { SearchAdapter } from "@cosmicdrift/kumiko-framework/search";
 import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 import { tenantEntity, tenantTable } from "../tenant/index.js";
 import {
@@ -222,6 +223,7 @@ export async function runNextDestructionStage(args: {
   readonly tenantId: TenantId;
   readonly log?: (message: string) => void;
   readonly fileProviderResolver?: FileProviderResolver;
+  readonly searchAdapter?: SearchAdapter;
   readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
   readonly actor?: string;
 }): Promise<{ readonly done: boolean; readonly error?: string; readonly halted?: boolean }> {
@@ -246,6 +248,7 @@ export async function runNextDestructionStage(args: {
     tenantId: args.tenantId,
     log: args.log,
     fileProviderResolver: args.fileProviderResolver,
+    searchAdapter: args.searchAdapter,
     escapeHatchAuditSink: args.escapeHatchAuditSink,
     actor: args.actor,
   };
@@ -334,6 +337,7 @@ export async function runTenantDestructionSweep(args: {
   readonly now?: Temporal.Instant;
   readonly log?: (message: string) => void;
   readonly fileProviderResolver?: FileProviderResolver;
+  readonly searchAdapter?: SearchAdapter;
   readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
   readonly actor?: string;
 }): Promise<{ readonly triggered: number; readonly advanced: number }> {
@@ -380,6 +384,7 @@ export async function runTenantDestructionSweep(args: {
         tenantId: row.id as TenantId,
         log: args.log,
         fileProviderResolver: args.fileProviderResolver,
+        searchAdapter: args.searchAdapter,
         escapeHatchAuditSink: args.escapeHatchAuditSink,
         actor: args.actor,
       });

package/packages/bundled-features/src/tenant-lifecycle/stages.ts

@@ -1,5 +1,9 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
-import { configuredPiiSubjectKms, type SubjectId } from "@cosmicdrift/kumiko-framework/crypto";
+import {
+  configuredPiiSubjectKms,
+  type SubjectId,
+  subjectIdToKey,
+} from "@cosmicdrift/kumiko-framework/crypto";
 import {
   createEventStoreExecutor,
   createTenantDb,
@@ -26,6 +30,10 @@ import {
   createEscapeHatchReporter,
   UNATTRIBUTED_ACTOR,
 } from "@cosmicdrift/kumiko-framework/pipeline";
+import {
+  purgeSearchDocumentsForSubject,
+  type SearchAdapter,
+} from "@cosmicdrift/kumiko-framework/search";
 import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 import {
   tenantEntity,
@@ -45,6 +53,9 @@ export type DestructionStageCtx = {
   // "destroyTenant" hooks) — undefined when no file-provider is wired,
   // which those hooks must treat as "nothing to clean up", not an error.
   readonly fileProviderResolver?: FileProviderResolver;
+  // Derived search docs of the tenant record (its name) live in the writer's
+  // index, not the destroyed tenant's, so the subject-keys stage purges them.
+  readonly searchAdapter?: SearchAdapter;
   // fw#2914 — sourced from the owning job's ctx (_escapeHatchAuditSink,
   // systemUser.id); runTenantDataHooks uses them to attribute+audit any
   // EXT_TENANT_DATA usage's declared escapeHatch.
@@ -123,8 +134,10 @@ async function eraseSubjectKeys(ctx: DestructionStageCtx): Promise<void> {
   const memberships = await selectMany<{ userId: string }>(ctx.db, tenantMembershipsTable, {
     tenantId: ctx.tenantId,
   });
+  const tenantRecordSubject: SubjectId = { kind: "record", entity: "tenant", id: ctx.tenantId };
   const subjects: SubjectId[] = [
     { kind: "tenant", tenantId: ctx.tenantId },
+    tenantRecordSubject,
     ...memberships.map((m) => ({ kind: "user" as const, userId: m.userId })),
   ];
   for (const subject of subjects) {
@@ -133,6 +146,15 @@ async function eraseSubjectKeys(ctx: DestructionStageCtx): Promise<void> {
       eraseReason: "tenant-destroy stage subject-keys",
     });
   }
+  if (ctx.searchAdapter) {
+    await purgeSearchDocumentsForSubject(
+      ctx.db,
+      ctx.registry.features,
+      ctx.searchAdapter,
+      subjectIdToKey(tenantRecordSubject),
+      tenantRecordSubject,
+    );
+  }
 }
 
 async function purgeTenantCache(ctx: DestructionStageCtx): Promise<void> {

package/packages/bundled-features/src/tier-engine/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.352.0",
+    "type": "improvement",
+    "title": "createTierOptionGate builds the availability rows and gates select options by tier on write",
+    "detail": "withTierOptionGate rejects a disallowed option with the lowest tier that allows it and lets an unchanged stored value pass on update."
+  },
   {
     "version": "0.278.0",
     "type": "breaking",

package/packages/bundled-features/src/tier-engine/index.ts

@@ -29,6 +29,13 @@ export {
   createTierEngineFeature,
   tierEngineFeature,
 } from "./feature.js";
+export {
+  createTierOptionGate,
+  type TierOptionAvailability,
+  type TierOptionGate,
+  type TierOptionGateDeps,
+  type TierOptionSpec,
+} from "./tier-option-gate.js";
 export {
   createTierResolver,
   type TierResolver,

package/packages/bundled-features/src/tier-engine/tier-option-gate.ts

@@ -0,0 +1,148 @@
+// Tier-gated options of a select field: one spec drives the availability query the
+// renderer shows (disabled option + "from <tier>" hint) and the write-path check that
+// actually enforces it, so the two cannot drift apart.
+
+import type { EntityTableMeta, SchemaTable, TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  UnprocessableError,
+  type WriteFailure,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+import { isPlainObject } from "@cosmicdrift/kumiko-framework/utils";
+import {
+  type CapGuardContext,
+  type CapLimitContext,
+  readPayloadField,
+} from "../cap-counter/index.js";
+
+export type TierOptionSpec<TCaps> = {
+  readonly field: string;
+  readonly options: readonly string[];
+  readonly isOptionAllowed: (option: string, caps: TCaps) => boolean;
+  readonly code: string;
+  readonly i18nKey: string;
+  /** Lets an update that resends the unchanged stored value of a no longer allowed
+   *  option pass (edit forms submit the whole row). Without it the stored value is not looked up. */
+  readonly table?: SchemaTable | EntityTableMeta;
+};
+
+export type TierOptionAvailability = {
+  readonly value: string;
+  readonly disabled: boolean;
+  readonly hint?: string;
+};
+
+export type TierOptionGateDeps<TTier extends string, TCaps> = {
+  /** Ascending: the first tier that allows an option is the one named as required. */
+  readonly tierOrder: readonly TTier[];
+  readonly capsForTier: (tier: TTier, context: CapLimitContext) => TCaps | Promise<TCaps>;
+  readonly resolveTier: (db: TenantDb) => Promise<TTier>;
+};
+
+export type TierOptionGate<TTier extends string, TCaps> = {
+  readonly optionAvailability: (
+    db: TenantDb,
+    context: CapLimitContext,
+    spec: Pick<TierOptionSpec<TCaps>, "options" | "isOptionAllowed">,
+    hintFor: (requiredTier: TTier) => string,
+  ) => Promise<readonly TierOptionAvailability[]>;
+  /** `recordId` is the id of the edited row; with `spec.table` it enables the unchanged-value pass. */
+  readonly checkTierOption: (
+    ctx: CapGuardContext,
+    value: unknown,
+    spec: TierOptionSpec<TCaps>,
+    recordId?: string,
+  ) => Promise<WriteFailure | null>;
+  readonly withTierOptionGate: (
+    handler: WriteHandlerDef,
+    spec: TierOptionSpec<TCaps>,
+  ) => WriteHandlerDef;
+};
+
+function limitContextOf(ctx: CapGuardContext): CapLimitContext {
+  return ctx.config ? { config: ctx.config } : {};
+}
+
+function recordIdOf(payload: unknown): string | undefined {
+  return isPlainObject(payload) && typeof payload["id"] === "string" ? payload["id"] : undefined;
+}
+
+export function createTierOptionGate<TTier extends string, TCaps>(
+  deps: TierOptionGateDeps<TTier, TCaps>,
+): TierOptionGate<TTier, TCaps> {
+  async function capsPerTier(
+    context: CapLimitContext,
+  ): Promise<readonly { readonly tier: TTier; readonly caps: TCaps }[]> {
+    return Promise.all(
+      deps.tierOrder.map(async (tier) => ({ tier, caps: await deps.capsForTier(tier, context) })),
+    );
+  }
+
+  async function optionAvailability(
+    db: TenantDb,
+    context: CapLimitContext,
+    spec: Pick<TierOptionSpec<TCaps>, "options" | "isOptionAllowed">,
+    hintFor: (requiredTier: TTier) => string,
+  ): Promise<readonly TierOptionAvailability[]> {
+    const currentCaps = await deps.capsForTier(await deps.resolveTier(db), context);
+    const tiers = await capsPerTier(context);
+    return spec.options.map((value) => {
+      if (spec.isOptionAllowed(value, currentCaps)) return { value, disabled: false };
+      const required = tiers.find(({ caps }) => spec.isOptionAllowed(value, caps));
+      return required === undefined
+        ? { value, disabled: true }
+        : { value, disabled: true, hint: hintFor(required.tier) };
+    });
+  }
+
+  async function storedValueMatches(
+    ctx: CapGuardContext,
+    spec: TierOptionSpec<TCaps>,
+    value: string,
+    recordId: string | undefined,
+  ): Promise<boolean> {
+    if (spec.table === undefined || recordId === undefined) return false;
+    const stored = await ctx.db.fetchOne<Record<string, unknown>>(spec.table, { id: recordId });
+    return stored?.[spec.field] === value;
+  }
+
+  async function checkTierOption(
+    ctx: CapGuardContext,
+    value: unknown,
+    spec: TierOptionSpec<TCaps>,
+    recordId?: string,
+  ): Promise<WriteFailure | null> {
+    // skip: an absent or non-string value is the schema's business, not a tier violation.
+    if (typeof value !== "string") return null;
+    const context = limitContextOf(ctx);
+    const currentCaps = await deps.capsForTier(await deps.resolveTier(ctx.db), context);
+    if (spec.isOptionAllowed(value, currentCaps)) return null;
+    if (await storedValueMatches(ctx, spec, value, recordId)) return null;
+    const required = (await capsPerTier(context)).find(({ caps }) =>
+      spec.isOptionAllowed(value, caps),
+    );
+    return writeFailure(
+      new UnprocessableError(spec.code, {
+        i18nKey: spec.i18nKey,
+        details: { field: spec.field, value, requiredTier: required?.tier },
+      }),
+    );
+  }
+
+  function withTierOptionGate(
+    handler: WriteHandlerDef,
+    spec: TierOptionSpec<TCaps>,
+  ): WriteHandlerDef {
+    return {
+      ...handler,
+      handler: async (event, ctx) => {
+        const value = readPayloadField(event.payload, spec.field);
+        const failure = await checkTierOption(ctx, value, spec, recordIdOf(event.payload));
+        return failure ?? handler.handler(event, ctx);
+      },
+    };
+  }
+
+  return { optionAvailability, checkTierOption, withTierOptionGate };
+}

package/packages/bundled-features/src/user/handlers/list.query.ts

@@ -8,7 +8,7 @@ import {
 import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
 import type { QueryHandlerDef } from "@cosmicdrift/kumiko-types/handlers";
 // kumiko-lint-ignore cross-feature-import SystemAdmin user-list joins memberships for tenants column
-import { tenantMembershipsTable, tenantTable } from "../../tenant/index.js";
+import { decryptTenantNames, tenantMembershipsTable, tenantTable } from "../../tenant/index.js";
 import { userEntity } from "../schema/user.js";
 
 const baseList = defineEntityListHandler("user", userEntity, {
@@ -82,7 +82,10 @@ export async function attachTenantLabels(
   ];
   const tenants =
     tenantIds.length > 0
-      ? await selectMany<TenantRow>(db, tenantTable, { id: { in: tenantIds } })
+      ? await decryptTenantNames(
+          await selectMany<TenantRow>(db, tenantTable, { id: { in: tenantIds } }),
+          "user:list",
+        )
       : [];
   const byUser = labelsByUserId(memberships, tenantLabelById(tenants));
   return rows.map((row) => {

package/packages/bundled-features/src/user-data-rights/boot-checks.ts

@@ -24,6 +24,13 @@ export function validateGdprHookCompleteness(features: readonly FeatureDefinitio
       if (usage.extensionName !== EXT_USER_DATA) continue;
       const hasExport = typeof usage.options?.["export"] === "function";
       const hasDelete = typeof usage.options?.["delete"] === "function";
+      // The compile-time "at least one hook" type is bypassed by string-typed
+      // extension names and casts; without this an empty bag registers nothing.
+      if (!hasExport && !hasDelete) {
+        throw new Error(
+          `[kumiko:boot] Feature "${feature.name}" registers EXT_USER_DATA for entity "${usage.entityName}" with neither an export nor a delete hook — the entity silently stays out of the Art.15/17/20 pipeline. Register at least one hook.`,
+        );
+      }
       if (hasExport && !hasDelete) {
         throw new Error(
           `[kumiko:boot] Feature "${feature.name}" exports entity "${usage.entityName}" via EXT_USER_DATA but registers no delete hook — data is included in Art.20 exports but never erased on forget (Art.17 violation). Add a delete hook. If erasure is intentionally handled elsewhere (e.g. crypto-shredding key-erase, parent cascade), register a no-op delete: async () => {} with a comment explaining why.`,

package/packages/bundled-features/src/user-data-rights/deletion-token.ts

@@ -38,7 +38,7 @@ export function redeemDeletionToken(args: {
   readonly secret: string | undefined;
   readonly loadPendingRequestId: (userId: string) => Promise<string | null>;
   // Spends the anchor AND performs the actual lifecycle transition in one
-  // atomic step (#3024) — the caller (confirm-deletion-by-token) folds the
+  // atomic step — the caller (confirm-deletion-by-token) folds the
   // Active→DeletionRequested write itself in here via `updateUserLifecycle`'s
   // `expect: { status: Active, pendingDeletionRequestId }`, so a write issued
   // after `ok: true` can't lose its work to a crash while the grant is

package/packages/bundled-features/src/user-data-rights/handlers/confirm-deletion-by-token.write.ts

@@ -37,7 +37,7 @@ async function readPendingDeletionRequestId(
 
 // Anonymous apex flow step 2: verify-link target. Verifies the HMAC token,
 // extracts the userId, and flips the grace period through the shared logic —
-// in ONE atomic step with the anchor spend (#3024): commitDeletion carries
+// in ONE atomic step with the anchor spend: commitDeletion carries
 // the actual grace-period transition, so a crash after the spend can no
 // longer lose the write step.
 //
@@ -47,7 +47,7 @@ async function readPendingDeletionRequestId(
 // a cancel-deletion (status → Active, pendingDeletionRequestId → null), a
 // replayed token fails against the nulled/renewed requestId — no re-arm.
 //
-// Concurrency (#3024): two simultaneous confirms of the same token both read
+// Concurrency: two simultaneous confirms of the same token both read
 // the same requestId and both verify the HMAC — commitDeletion spends the
 // anchor AND writes the transition atomically (expect: status===Active &&
 // pendingDeletionRequestId===requestId), so exactly one wins. The loser gets

package/packages/bundled-features/src/user-data-rights-defaults/hooks/delivery-attempt.userdata-hook.ts

@@ -1,5 +1,12 @@
 import type { UserDataDeleteHook, UserDataExportHook } from "@cosmicdrift/kumiko-framework/engine";
-import { deliveryAttemptsTable } from "../../delivery/index.js";
+import {
+  appendEventInTenantDb,
+  getStreamVersionInTenantDb,
+} from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  DELIVERY_ATTEMPT_ADDRESS_ERASED_EVENT,
+  deliveryAttemptsTable,
+} from "../../delivery/index.js";
 import { featureMounted } from "./feature-mounted.js";
 
 // userData-Hooks for delivery's attempt log (deferred from #797, closed by
@@ -28,9 +35,32 @@ export const deliveryAttemptExportHook: UserDataExportHook = async (ctx) => {
   };
 };
 
-export const deliveryAttemptDeleteHook: UserDataDeleteHook = async () => {
-  // Deliberate no-op: erasure runs via crypto-shredding — the forget pipeline
-  // erases the recipient's DEK, which makes recipientAddress unreadable in
-  // BOTH the append-only events and the projected rows (#799). A read-side
-  // UPDATE here would be wiped on the next projection rebuild anyway.
+// Both strategies erase the address. The DEK shredding of a forget covers KMS deployments; the
+// erase event also covers plaintext mode, and unlike a read-side UPDATE it survives a projection
+// rebuild. Rows without an address are skipped, which makes a second run a no-op.
+export const deliveryAttemptDeleteHook: UserDataDeleteHook = async (ctx) => {
+  // skip: delivery not mounted — its table doesn't exist, nothing to erase.
+  if (!featureMounted(ctx, "delivery")) return;
+  const rows = await ctx.db.selectMany<{ id: string; recipientAddress: string | null }>(
+    deliveryAttemptsTable,
+    {
+      tenantId: ctx.tenantId,
+      recipientId: ctx.userId,
+    },
+  );
+  for (const row of rows) {
+    if (row.recipientAddress === null) continue;
+    await appendEventInTenantDb(
+      ctx.db,
+      {
+        aggregateType: "deliveryAttempt",
+        aggregateId: row.id,
+        expectedVersion: await getStreamVersionInTenantDb(ctx.db, row.id),
+        type: DELIVERY_ATTEMPT_ADDRESS_ERASED_EVENT,
+        payload: {},
+        metadata: { userId: "system" },
+      },
+      { registry: ctx.registry },
+    );
+  }
 };

package/packages/bundled-features/src/workflow-runner/changes.json

@@ -1,4 +1,9 @@
 [
+  {
+    "version": "0.353.0",
+    "type": "fix",
+    "title": "workflow.run-failed carries the real stepIndex when a run suspends in an unsupported step"
+  },
   {
     "version": "0.340.0",
     "type": "improvement",

package/packages/bundled-features/src/workflow-runner/event-trigger.ts

@@ -23,7 +23,11 @@ import {
 import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
 import { workflowRunAggregateId } from "./aggregate-id.js";
 import { registerEventWakeup } from "./event-subscriber.js";
-import { startAndRunWorkflow, type WorkflowRunFailedPayload } from "./runner.js";
+import {
+  startAndRunWorkflow,
+  type WorkflowRunFailedPayload,
+  WorkflowSuspensionUnsupportedError,
+} from "./runner.js";
 import { registerWorkflow } from "./workflow-registry.js";
 
 const log = createFallbackLogger("workflow-runner");
@@ -98,15 +102,19 @@ export function registerEventTrigger(r: FeatureRegistrar, workflow: WorkflowDefi
             handlerCtx: ctx as never,
           });
         } catch (error) {
+          // Only the suspension error knows its step; a throw inside a step
+          // carries no index, so it still reports 0.
+          const stepIndex =
+            error instanceof WorkflowSuspensionUnsupportedError ? error.stepIndex : 0;
           log.warn("workflow run failed", {
             runId,
             workflowName: workflow.name,
-            stepIndex: 0,
+            stepIndex,
             error: String(error),
           });
           const failedPayload: WorkflowRunFailedPayload = {
             workflowName: workflow.name,
-            stepIndex: 0,
+            stepIndex,
             error: describeWorkflowStepError(error),
           };
           await ctx.unsafeAppendEvent({

package/packages/bundled-features/src/workflow-runner/handlers/resume-run.write.ts

@@ -92,6 +92,11 @@ function checkQ7Fingerprint(
   storedFingerprint: string | null,
 ): WorkflowRunFailedPayload | null {
   const currentFingerprint = computeDefinitionFingerprint(workflow);
+  if (storedFingerprint === null) {
+    log.warn(
+      `Run ${runId} of workflow "${workflowName}" has no stored definition fingerprint — resuming against the current definition unchecked.`,
+    );
+  }
   const fingerprintChanged = storedFingerprint !== null && currentFingerprint !== storedFingerprint;
   if (!fingerprintChanged) {
     return null;

package/samples/apps/marketing-demo/src/app/seed-data.ts

@@ -306,7 +306,7 @@ export const ASSET_TEMPLATES: ReadonlyArray<AssetTemplate> = [
 // treffen ohne Sonderfall. Wird nur für status==="lent" konsultiert.
 export const OWNERS: ReadonlyArray<string> = [
   "",
-  "Marc Frost",
+  "Alex Morgan",
   "Anna Weber",
   "Lars Bergmann",
   "Sina Klein",
@@ -435,7 +435,7 @@ export const REPORTERS: ReadonlyArray<string> = [
 // unzugewiesen damit die Liste nicht zu uniform aussieht.
 export const ASSIGNEES: ReadonlyArray<string> = [
   "",
-  "Marc Frost",
+  "Alex Morgan",
   "IT-Team",
   "Sysadmin",
   "Helpdesk-L1",

package/samples/apps/showcase/src/features/items/schema/item.ts

@@ -53,7 +53,6 @@ export const itemEditScreen: EntityEditScreenDefinition = {
   type: "entityEdit",
   entity: "item",
   layout: {
-    width: "3xl",
     sections: [
       {
         title: "Basics",

package/samples/apps/styleguide/src/app/shell.tsx

@@ -58,7 +58,7 @@ export function AppShell({
           ],
         ])
       }
-      sidebarFooter={<SidebarUser name="Marc Frost" email="marc@cosmicdrift.dev" />}
+      sidebarFooter={<SidebarUser name="Alex Morgan" email="alex@example.com" />}
     >
       {activeTarget !== undefined ? <EditorPanel resolvers={resolvers} /> : children}
     </DefaultAppShell>

package/samples/apps/styleguide/src/features/gallery/web/Gallery.tsx

@@ -606,20 +606,26 @@ export function Gallery(): ReactNode {
           <div className="flex flex-col gap-5 px-6 py-6">
             <div className="flex items-center gap-4">
               <div className="bg-muted text-foreground flex size-16 items-center justify-center rounded-full text-lg font-semibold">
-                MF
+                AM
               </div>
               <Button variant="secondary">Change avatar</Button>
             </div>
             <div className="grid gap-4 sm:grid-cols-2">
               <Field id="pf-name" label="Full name">
-                <Input kind="text" id="pf-name" name="pf-name" value="Marc Frost" onChange={noop} />
+                <Input
+                  kind="text"
+                  id="pf-name"
+                  name="pf-name"
+                  value="Alex Morgan"
+                  onChange={noop}
+                />
               </Field>
               <Field id="pf-email" label="Email">
                 <Input
                   kind="text"
                   id="pf-email"
                   name="pf-email"
-                  value="marc@cosmicdrift.dev"
+                  value="alex@example.com"
                   onChange={noop}
                 />
               </Field>

package/samples/apps/styleguide/src/features/widgets/demo-locale.ts

@@ -0,0 +1,47 @@
+// Server-side locale helpers for the dashboard demo queries. Not shared with
+// renderer-web's format.ts: server code must not import renderer-web.
+
+import { WIDGETS_I18N } from "./i18n";
+
+type WidgetsI18nKey = keyof typeof WIDGETS_I18N;
+type DemoCurrency = "EUR" | "USD";
+
+const FALLBACK_LOCALE = "en";
+
+// Intl throws RangeError on malformed tags.
+function usableLocale(locale: string): string {
+  try {
+    return Intl.getCanonicalLocales(locale)[0] ?? FALLBACK_LOCALE;
+  } catch {
+    return FALLBACK_LOCALE;
+  }
+}
+
+// The bundle only carries de + en: any "de" tag ("de-AT") picks de, everything else en.
+export function demoText(key: WidgetsI18nKey, locale: string): string {
+  const entry = WIDGETS_I18N[key];
+  const primarySubtag = usableLocale(locale).split("-")[0];
+  return primarySubtag === "de" ? entry.de : entry.en;
+}
+
+export function demoMoney(amount: number, currency: DemoCurrency, locale: string): string {
+  return new Intl.NumberFormat(usableLocale(locale), {
+    style: "currency",
+    currency,
+    maximumFractionDigits: 0,
+  }).format(amount);
+}
+
+export function demoPercent(fraction: number, locale: string): string {
+  return new Intl.NumberFormat(usableLocale(locale), {
+    style: "percent",
+    maximumFractionDigits: 0,
+  }).format(fraction);
+}
+
+export function demoMonthYear(year: number, month: number, locale: string): string {
+  return Temporal.PlainDate.from({ year, month, day: 1 }).toLocaleString(usableLocale(locale), {
+    month: "short",
+    year: "numeric",
+  });
+}