@cosmicdrift/kumiko-samples 0.362.0 → 0.364.0

package/packages/bundled-features/src/template-resolver/web/document-toolbar-blocks.ts

@@ -0,0 +1,72 @@
+// @runtime client
+import type { ContentEditorProps } from "@cosmicdrift/kumiko-renderer";
+import type { ReactNode } from "react";
+
+export type DocumentToolbarBlock =
+  | "image"
+  | "table"
+  | "button"
+  | "divider"
+  | "repeat"
+  | "pageBreak"
+  | "align";
+
+/** Imperative access for an outside panel (placeholder list, resource list). */
+export type DocumentEditorHandle = {
+  readonly insertPlaceholder: (name: string) => void;
+  readonly insertResource: (key: string, alt?: string) => void;
+  readonly focus: () => void;
+};
+
+export type DocumentResourcePreview = {
+  /** Shown as the image source in the editor only; never written to the document. */
+  readonly src: string;
+  readonly caption?: string;
+};
+
+/** "default" keeps the compact bordered editor; "canvas" renders a flat text
+ *  toolbar and a paper-like page with block labels. */
+export type DocumentEditorChrome = "default" | "canvas";
+
+export type DocumentEditorProps = ContentEditorProps & {
+  readonly blocks?: readonly DocumentToolbarBlock[];
+  /** Display label per variable name, as inserted (list item fields use the
+   *  dotted form, e.g. "lines.description"). A chip shows label and name. */
+  readonly variableLabels?: Readonly<Record<string, string>>;
+  /** Variable names rendered as system chips (a different tint). */
+  readonly systemVariables?: readonly string[];
+  /** Image previews by resource key; resources without one show a key placeholder. */
+  readonly resourcePreviews?: Readonly<Record<string, DocumentResourcePreview>>;
+  readonly chrome?: DocumentEditorChrome;
+  /** "compact" renders the placeholder and block buttons icon-only with a tooltip, for narrow columns. Default "full". */
+  readonly toolbar?: "full" | "compact";
+  /** Canvas only: wraps the editable area in a caller-owned page (letterhead, margins) instead of the default mail paper. */
+  readonly renderPaper?: (editable: ReactNode) => ReactNode;
+  /** Canvas only: renders the toolbar (and its insert panel) into this element instead of above the editor;
+   *  null renders none. Lets several region editors share one toolbar that follows the focused one. */
+  readonly toolbarHost?: HTMLElement | null;
+  /** Called with the handle once the editor exists and with null when it is destroyed. */
+  readonly onEditorReady?: (handle: DocumentEditorHandle) => void;
+};
+
+export const MAIL_DOCUMENT_BLOCKS = [
+  "image",
+  "table",
+  "button",
+  "divider",
+  "repeat",
+] as const satisfies readonly DocumentToolbarBlock[];
+
+export const PDF_DOCUMENT_BLOCKS = [
+  "align",
+  "image",
+  "table",
+  "divider",
+  "repeat",
+  "pageBreak",
+] as const satisfies readonly DocumentToolbarBlock[];
+
+/** Block set for a template-resource kind; every kind except "document-pdf" gets the mail set. */
+export function documentBlocksForKind(kind: string | undefined): readonly DocumentToolbarBlock[] {
+  return kind === "document-pdf" ? PDF_DOCUMENT_BLOCKS : MAIL_DOCUMENT_BLOCKS;
+}

package/packages/bundled-features/src/template-resolver/web/editor-handle.ts

@@ -0,0 +1,26 @@
+// @runtime client
+import type { Editor } from "@tiptap/core";
+import { isDocumentReferenceName, isDocumentResourceKey } from "../document-schema.js";
+import type { DocumentEditorHandle } from "./document-toolbar-blocks.js";
+
+export function createEditorHandle(editor: Editor): DocumentEditorHandle {
+  return {
+    insertPlaceholder: (name) => {
+      // skip: an invalid variable name is not insertable
+      if (!isDocumentReferenceName(name)) return;
+      editor.chain().focus().insertContent({ type: "variable", attrs: { name } }).run();
+    },
+    insertResource: (key, alt) => {
+      // skip: an invalid resource key is not insertable
+      if (!isDocumentResourceKey(key)) return;
+      editor
+        .chain()
+        .focus()
+        .insertContent({ type: "resource", attrs: { resource: key, alt: alt ?? null } })
+        .run();
+    },
+    focus: () => {
+      editor.commands.focus();
+    },
+  };
+}

package/packages/bundled-features/src/template-resolver/web/i18n.ts

@@ -9,12 +9,133 @@ import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
 
 export const defaultTranslations: TranslationsByLocale = {
   en: {
+    "template-resolver.documentEditor.button": "Button",
+    "template-resolver.documentEditor.buttonDefaultText": "Confirm",
+    "template-resolver.documentEditor.buttonTarget": "Button target",
+    "template-resolver.documentEditor.buttonText": "Button text",
+    "template-resolver.documentEditor.cancel": "Cancel",
+    "template-resolver.documentEditor.divider": "Divider",
+    "template-resolver.documentEditor.heading3": "Heading 3",
+    "template-resolver.documentEditor.image": "Image",
+    "template-resolver.documentEditor.imageBlock": "Image · inline",
+    "template-resolver.documentEditor.imageAlt": "Alt text (optional)",
+    "template-resolver.documentEditor.insert": "Insert",
+    "template-resolver.documentEditor.insertPlaceholder": "Placeholder",
+    "template-resolver.documentEditor.invalidImageAlt": "The alt text must not contain < or >.",
+    "template-resolver.documentEditor.invalidLink":
+      "This link target is not allowed. Use https, http, mailto, tel or a placeholder.",
+    "template-resolver.documentEditor.invalidResourceKey": "This resource key is not valid.",
+    "template-resolver.documentEditor.link": "Link",
+    "template-resolver.documentEditor.linkHref": "Link target",
+    "template-resolver.documentEditor.linkHrefPlaceholder": "https://",
+    "template-resolver.documentEditor.noVariables": "No matching variables are available here.",
+    "template-resolver.documentEditor.pageBreak": "Page break",
+    "template-resolver.documentEditor.align": "Align",
+    "template-resolver.documentEditor.alignLeft": "Left",
+    "template-resolver.documentEditor.alignCenter": "Centered",
+    "template-resolver.documentEditor.alignRight": "Right",
+    "template-resolver.documentEditor.alignJustify": "Justified",
+    "template-resolver.documentEditor.repeatBarList": "Repeat · {list}",
+    "template-resolver.documentEditor.repeatHeader": "Repeat header row",
+    "template-resolver.documentEditor.paragraph": "Paragraph",
+    "template-resolver.documentEditor.paragraphStyle": "Paragraph style",
+    "template-resolver.documentEditor.placeholder": "Write your text…",
+    "template-resolver.documentEditor.removeLink": "Remove link",
+    "template-resolver.documentEditor.repeat": "Repeat",
+    "template-resolver.documentEditor.repeatList": "List to repeat",
+    "template-resolver.documentEditor.resourceKey": "Resource key",
+    "template-resolver.documentEditor.table": "Table",
     "template-resolver.editor.titleLabel": "Title",
     "template-resolver.editor.contentLabel": "Content",
     "template-resolver.editor.save": "Save",
     "template-resolver.editor.saving": "Saving…",
     "template-resolver.editor.created": "Created.",
     "template-resolver.editor.saved": "Saved.",
+    "templateResolver.errors.document.buttonHrefNotPlaceholder":
+      "The button target “{detail}” must be a placeholder.",
+    "templateResolver.errors.document.disallowedLinkHref":
+      "Link target “{detail}” is not allowed; use https, http, mailto, tel or a placeholder.",
+    "templateResolver.errors.document.documentRequiresHtmlFormat":
+      "This template kind requires the html format, got “{detail}”.",
+    "templateResolver.errors.document.layoutRequiresMjmlFormat":
+      "Mail layouts require the mjml format, got “{detail}”.",
+    "templateResolver.errors.document.layoutInvalidStructure":
+      "The layout may only contain the header, content, signature and footer regions: {detail}.",
+    "templateResolver.errors.document.layoutMissingContentSlot":
+      "The layout needs its content slot: {detail}.",
+    "templateResolver.errors.document.layoutSourceSystemOnly":
+      "Only system layouts may use {detail} source; use the structured html layout.",
+    "templateResolver.errors.template.targetExists":
+      "A template for locale “{detail}” already exists; overwrite it explicitly to replace it.",
+    "templateResolver.warnings.resourceNotUploaded": "Image not uploaded: {detail}",
+    "templateResolver.checks.resourcesResolved": "All images are available",
+    "templateResolver.checks.textPresent": "A plain-text version is present",
+    "templateResolver.checks.sizeUnderCap": "The mail is within the 10 MiB size limit",
+    "templateResolver.checks.requiredPlaceholders": "All required placeholders are used",
+    "templateResolver.errors.preview.renderFailed": "The preview could not be rendered.",
+    "templateResolver.errors.testMail.noChannel":
+      "No email channel is set up, so no test mail can be sent.",
+    "templateResolver.errors.testMail.noAddress":
+      "Your account has no email address to send the test mail to.",
+    "templateResolver.errors.testMail.failed": "The test mail could not be sent.",
+    "templateResolver.errors.resource.tooLarge": "The image is too large.",
+    "templateResolver.errors.resource.unsupportedImage":
+      "This file is not a supported image. Use PNG, JPEG, WebP or GIF.",
+    "templateResolver.errors.template.systemResourcesNeedSystemTenant":
+      "Resource files of system templates can only be imported or exported by a user of the system tenant.",
+    "templateResolver.errors.template.bundleLocalesDiffer":
+      "The locales of this template differ in content format or variables, so they cannot be exported as one bundle.",
+    "templateResolver.errors.collection.kindNotAllowed":
+      "“{detail}” templates are written through their own editor, not through a collection.",
+    "templateResolver.errors.noSystemTemplate": "There is no active system template to reset to.",
+    "templateResolver.errors.noDraft": "There is no draft to discard.",
+    "templateResolver.errors.template.invalidMeta": "The template settings are invalid.",
+    "templateResolver.errors.template.meta.subject.required": "The subject is missing.",
+    "templateResolver.errors.template.meta.subject.invalid":
+      "The subject is invalid (at most 200 characters, no line breaks).",
+    "templateResolver.errors.template.meta.previewText.required": "The preview text is missing.",
+    "templateResolver.errors.template.meta.previewText.invalid":
+      "The preview text is invalid (at most 200 characters, no line breaks).",
+    "templateResolver.errors.template.meta.senderName.required": "The sender name is missing.",
+    "templateResolver.errors.template.meta.senderName.invalid":
+      "The sender name is invalid (at most 80 characters, no line breaks).",
+    "templateResolver.errors.template.meta.replyTo.required": "The reply-to address is missing.",
+    "templateResolver.errors.template.meta.replyTo.invalid":
+      "The reply-to address is not a valid email address.",
+    "templateResolver.errors.template.meta.layoutSlug.required": "The layout is missing.",
+    "templateResolver.errors.template.meta.layoutSlug.invalid": "The chosen layout is invalid.",
+    "templateResolver.errors.template.meta.fileName.required": "The file name is missing.",
+    "templateResolver.errors.template.meta.fileName.invalid":
+      "The file name is invalid: no slashes, quotes, semicolons or two dots in a row.",
+    "templateResolver.errors.template.unknownPlaceholders": "Unknown placeholders: {detail}",
+    "templateResolver.errors.template.missingRequiredPlaceholders":
+      "Required placeholders are not used: {detail}",
+    "templateResolver.errors.document.embeddedContent":
+      "<{detail}> elements are not allowed in template bodies.",
+    "templateResolver.errors.document.unsafeAttributeValue":
+      "The attribute value “{detail}” must not contain < or >.",
+    "templateResolver.errors.document.eventHandlerAttribute":
+      "Inline event handler “{detail}” is not allowed.",
+    "templateResolver.errors.document.externalImageSource":
+      "Images must reference an uploaded resource; image source “{detail}” is not allowed.",
+    "templateResolver.errors.document.imageWithoutResource":
+      "Images must reference an uploaded resource.",
+    "templateResolver.errors.document.invalidReferenceName": "“{detail}” is not a valid name.",
+    "templateResolver.errors.document.scriptElement":
+      "<script> elements are not allowed in template bodies.",
+    "templateResolver.errors.attachment.unsupportedType":
+      "Attachments must be a PDF, PNG or JPEG file.",
+    "templateResolver.errors.attachment.limit": "A template can have at most {max} attachments.",
+    "templateResolver.errors.attachment.invalid":
+      "The attachment needs a template, a key and a valid file name.",
+    "templateResolver.errors.attachment.pdfTemplateMissing":
+      "There is no PDF template “{slug}” for this tenant or the system.",
+    "template-resolver.documentEditor.htmlSource": "HTML source",
+    "template-resolver.documentEditor.removeBlock": "Remove block",
+    "template-resolver.documentEditor.list": "List",
+    "template-resolver.documentEditor.more": "More",
+    "template-resolver.documentEditor.showHtml": "HTML",
+    "template-resolver.documentEditor.underline": "Underline",
     "template-resolver.editor.saveFailed": "Save failed.",
     "template-resolver.editor.networkError": "Network error while saving.",
     "template-resolver.editor.loading": "Loading current version…",

package/packages/bundled-features/src/template-resolver/web/index.ts

@@ -5,4 +5,30 @@
 // `@cosmicdrift/kumiko-bundled-features/template-resolver` and has no React or
 // DOM deps.
 
+export {
+  PDF_DEFAULT_MARGIN_MM,
+  PDF_FOOTER_MARGIN_MM,
+  PDF_HEADER_MARGIN_MM,
+  PDF_ORIENTATIONS,
+  PDF_PAGE_FORMATS,
+} from "../pdf-constants.js";
+export {
+  TemplateResolverErrors,
+  TemplateResolverHandlers,
+  TemplateResolverQueries,
+} from "../qualified-names.js";
 export { textBlocksClient } from "./client-plugin.js";
+export { DocumentContentEditor } from "./document-editor.js";
+export {
+  type DocumentEditorChrome,
+  type DocumentEditorHandle,
+  type DocumentEditorProps,
+  type DocumentResourcePreview,
+  type DocumentToolbarBlock,
+  MAIL_DOCUMENT_BLOCKS,
+  PDF_DOCUMENT_BLOCKS,
+} from "./document-toolbar-blocks.js";
+export {
+  PlaceholderLineEditor,
+  type PlaceholderLineEditorProps,
+} from "./placeholder-line-editor-lazy.js";

package/packages/bundled-features/src/template-resolver/web/placeholder-line-editor-lazy.tsx

@@ -0,0 +1,36 @@
+// @runtime client
+//
+// Lazy boundary for the placeholder line editor: tiptap loads with the chunk,
+// the fallback is a plain text input holding the same `{{name}}` text.
+// Never import placeholder-line-editor statically here.
+
+import { usePrimitives } from "@cosmicdrift/kumiko-renderer";
+import { lazy, type ReactNode, Suspense } from "react";
+import type { PlaceholderLineEditorProps } from "./placeholder-line-editor.js";
+
+export type { PlaceholderLineEditorProps } from "./placeholder-line-editor.js";
+
+const LazyPlaceholderLineEditor = lazy(() => import("./placeholder-line-editor.js"));
+
+function PlainLineFallback({
+  id,
+  value,
+  onChange,
+  readOnly = false,
+  "aria-label": ariaLabel,
+}: PlaceholderLineEditorProps): ReactNode {
+  const { Field, Input } = usePrimitives();
+  return (
+    <Field id={id} label={ariaLabel} hideLabel>
+      <Input kind="text" id={id} name={id} value={value} onChange={onChange} disabled={readOnly} />
+    </Field>
+  );
+}
+
+export function PlaceholderLineEditor(props: PlaceholderLineEditorProps): ReactNode {
+  return (
+    <Suspense fallback={<PlainLineFallback {...props} />}>
+      <LazyPlaceholderLineEditor {...props} />
+    </Suspense>
+  );
+}

package/packages/bundled-features/src/template-resolver/web/placeholder-line-editor.tsx

@@ -0,0 +1,176 @@
+// @runtime client
+//
+// Single-line editor for plain-text fields that carry {{placeholders}}
+// (subject, preheader). The stored value stays plain text; placeholders show
+// as chips while editing. Lives in the same lazy chunk as the document editor.
+
+import { cn } from "@cosmicdrift/kumiko-renderer-web";
+import { Extension, Node } from "@tiptap/core";
+import { UndoRedo } from "@tiptap/extensions";
+import { EditorContent, useEditor } from "@tiptap/react";
+import StarterKit from "@tiptap/starter-kit";
+import { type ReactNode, useMemo, useState } from "react";
+import { DocumentVariable } from "../document-schema.js";
+import { createVariableView } from "./document-editor-extensions.js";
+import type { DocumentEditorHandle } from "./document-toolbar-blocks.js";
+import { createEditorHandle } from "./editor-handle.js";
+import { contentToLine, lineToContent, singleLine } from "./placeholder-text.js";
+import { useStableByKey } from "./use-stable-by-key.js";
+
+export type PlaceholderLineEditorProps = {
+  readonly id: string;
+  /** Plain text with `{{name}}` placeholders. */
+  readonly value: string;
+  readonly onChange: (value: string) => void;
+  readonly variableLabels?: Readonly<Record<string, string>>;
+  /** Placeholders shown as system chips (a different tint). */
+  readonly systemVariables?: readonly string[];
+  readonly readOnly?: boolean;
+  /** Drops the input frame so the line sits flat inside a label/value row. */
+  readonly flat?: boolean;
+  readonly onEditorReady?: (handle: DocumentEditorHandle) => void;
+  readonly "aria-label": string;
+};
+
+const LineDocument = Node.create({ name: "doc", topNode: true, content: "paragraph" });
+
+// One line only: Enter must not split the paragraph.
+const BlockLineBreaks = Extension.create({
+  name: "blockLineBreaks",
+  addKeyboardShortcuts() {
+    return { Enter: () => true, "Shift-Enter": () => true, "Mod-Enter": () => true };
+  },
+});
+
+const NO_LABELS: Readonly<Record<string, string>> = {};
+const NO_NAMES: readonly string[] = [];
+
+function LineEditorBody({
+  id,
+  initialValue,
+  onChange,
+  variableLabels,
+  systemVariables,
+  readOnly,
+  flat,
+  onEditorReady,
+  ariaLabel,
+}: {
+  readonly id: string;
+  readonly initialValue: string;
+  readonly onChange: (value: string) => void;
+  readonly variableLabels: Readonly<Record<string, string>>;
+  readonly systemVariables: readonly string[];
+  readonly readOnly: boolean;
+  readonly flat: boolean;
+  readonly onEditorReady: ((handle: DocumentEditorHandle) => void) | undefined;
+  readonly ariaLabel: string;
+}): ReactNode {
+  const extensions = useMemo(
+    () => [
+      LineDocument,
+      StarterKit.configure({
+        document: false,
+        blockquote: false,
+        bold: false,
+        bulletList: false,
+        code: false,
+        codeBlock: false,
+        dropcursor: false,
+        gapcursor: false,
+        hardBreak: false,
+        heading: false,
+        horizontalRule: false,
+        italic: false,
+        link: false,
+        listItem: false,
+        listKeymap: false,
+        orderedList: false,
+        strike: false,
+        trailingNode: false,
+        underline: false,
+        undoRedo: false,
+      }),
+      DocumentVariable.extend({
+        addNodeView: () => createVariableView(variableLabels, systemVariables, flat),
+      }),
+      UndoRedo,
+      BlockLineBreaks,
+    ],
+    [variableLabels, systemVariables, flat],
+  );
+
+  const editor = useEditor({
+    extensions,
+    content: {
+      type: "doc",
+      content: [{ type: "paragraph", content: lineToContent(initialValue) }],
+    },
+    editable: !readOnly,
+    immediatelyRender: false,
+    editorProps: {
+      attributes: { id, role: "textbox", "aria-label": ariaLabel, "aria-multiline": "false" },
+      transformPastedText: singleLine,
+      // Rich pastes would bring several paragraphs; only their text is kept.
+      transformPastedHTML: (html) => singleLine(html.replace(/<[^>]*>/g, " ")),
+    },
+    onCreate: ({ editor: created }) => onEditorReady?.(createEditorHandle(created)),
+    onUpdate: ({ editor: e }) => onChange(contentToLine(e.getJSON().content?.[0]?.content)),
+  });
+
+  return (
+    <EditorContent
+      editor={editor}
+      className={cn(
+        "flex items-center bg-transparent text-base md:text-sm",
+        flat ? "min-h-10" : "min-h-9 rounded-md border border-input px-3",
+        "[&_.ProseMirror]:w-full [&_.ProseMirror]:whitespace-nowrap [&_.ProseMirror]:outline-none",
+        "[&_p]:m-0",
+        readOnly && "opacity-60",
+      )}
+    />
+  );
+}
+
+export default function PlaceholderLineEditor({
+  id,
+  value,
+  onChange,
+  variableLabels = NO_LABELS,
+  systemVariables = NO_NAMES,
+  readOnly = false,
+  flat = false,
+  onEditorReady,
+  "aria-label": ariaLabel,
+}: PlaceholderLineEditorProps): ReactNode {
+  const stableLabels = useStableByKey(variableLabels, JSON.stringify(variableLabels));
+  const stableSystem = useStableByKey(systemVariables, systemVariables.join("\n"));
+
+  // The text is the source of truth. Typing reports it through onChange and
+  // keeps `emitted` equal to `value`; any other value (async load, reset)
+  // remounts the editor body on the new text.
+  const [emitted, setEmitted] = useState(value);
+  const [epoch, setEpoch] = useState(0);
+  if (value !== emitted) {
+    setEmitted(value);
+    setEpoch((current) => current + 1);
+  }
+
+  return (
+    <LineEditorBody
+      key={`${epoch}-${readOnly}-${JSON.stringify(stableLabels)}`}
+      id={id}
+      initialValue={value}
+      onChange={(next) => {
+        setEmitted(next);
+        onChange(next);
+      }}
+      variableLabels={stableLabels}
+      systemVariables={stableSystem}
+      readOnly={readOnly}
+      flat={flat}
+      onEditorReady={onEditorReady}
+      ariaLabel={ariaLabel}
+    />
+  );
+}

package/packages/bundled-features/src/template-resolver/web/placeholder-text.ts

@@ -0,0 +1,37 @@
+// @runtime client
+import type { JSONContent } from "@tiptap/core";
+import { isDocumentReferenceName } from "../document-schema.js";
+
+const PLACEHOLDER_TOKEN = /\{\{([^{}]*)\}\}/g;
+
+// Names the schema refuses stay plain text, so a typo never becomes a chip
+// that the server would reject.
+export function lineToContent(text: string): JSONContent[] {
+  const content: JSONContent[] = [];
+  let cursor = 0;
+  const pushText = (value: string): void => {
+    if (value !== "") content.push({ type: "text", text: value });
+  };
+  for (const match of text.matchAll(PLACEHOLDER_TOKEN)) {
+    const name = match[1] ?? "";
+    if (!isDocumentReferenceName(name)) continue;
+    pushText(text.slice(cursor, match.index));
+    content.push({ type: "variable", attrs: { name } });
+    cursor = match.index + match[0].length;
+  }
+  pushText(text.slice(cursor));
+  return content;
+}
+
+export function contentToLine(nodes: readonly JSONContent[] | undefined): string {
+  return (nodes ?? [])
+    .map((node) => {
+      if (node.type === "variable") return `{{${String(node.attrs?.["name"])}}}`;
+      return node.type === "text" ? (node.text ?? "") : "";
+    })
+    .join("");
+}
+
+export function singleLine(text: string): string {
+  return text.replace(/\s*[\r\n]+\s*/g, " ");
+}

package/packages/bundled-features/src/template-resolver/web/use-stable-by-key.ts

@@ -0,0 +1,14 @@
+// @runtime client
+import { useState } from "react";
+
+// Callers often pass fresh object literals every render; this keeps the first
+// value for as long as the content key is unchanged, so memoized extension
+// lists (and the editor built from them) are not rebuilt on every render.
+export function useStableByKey<T>(value: T, key: string): T {
+  const [stored, setStored] = useState({ key, value });
+  if (stored.key !== key) {
+    setStored({ key, value });
+    return value;
+  }
+  return stored.value;
+}

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

@@ -7,6 +7,7 @@ import {
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import { errorCodeOf, isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
 import * as z from "zod";
 import { userSessionTable } from "../../sessions/index.js";
 import { decryptStoredPii, mapWithConcurrency } from "../../shared/index.js";
@@ -37,7 +38,7 @@ const SORT_FIELDS = ["email", "status", "createdAt", "lastSeenAt"] as const;
 type SortField = (typeof SORT_FIELDS)[number];
 
 function isSortField(value: string): value is SortField {
-  return (SORT_FIELDS as readonly string[]).includes(value);
+  return isOneOf(SORT_FIELDS, value);
 }
 
 // Nulls (no session yet, invitation rows) sort last regardless of
@@ -141,7 +142,7 @@ export const teamListQuery = definePagedQueryHandler({
         // ponytail: lean sample apps (admin-console) mount auth without
         // sessions — store_user_sessions never gets pushed. Integration tests
         // may seed the table without mounting the feature; prod mounts both.
-        if ((err as { code?: string }).code !== "42P01") throw err;
+        if (errorCodeOf(err) !== "42P01") throw err;
       }
     }
 

package/packages/bundled-features/src/tenant/seeding.ts

@@ -44,7 +44,10 @@ import {
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { getUnscopedAggregateStreamMaxVersion } from "@cosmicdrift/kumiko-framework/event-store";
-import { createLifecycleHooks } from "@cosmicdrift/kumiko-framework/pipeline";
+import {
+  createDeferringNotify,
+  createLifecycleHooks,
+} from "@cosmicdrift/kumiko-framework/pipeline";
 import { TestUsers } from "@cosmicdrift/kumiko-framework/stack";
 import { assertAssignableMembershipRoles } from "./membership-roles.js";
 import { tenantMembershipEntity, tenantMembershipsTable } from "./membership-table.js";
@@ -118,12 +121,40 @@ export type SeedTenantHooks = {
 // dispatcher's sink and flush post-commit. Without a sink (fixture / plain
 // Connection) they still fire immediately — there is no outer TX to wait for.
 //
+function buildSeedHookNotify(
+  context: AppContext,
+  scopedUser: SessionUser,
+  targetTenantId: TenantId,
+  notifyTiming: "deferUntilCommit" | "inline",
+): AppContext["notify"] {
+  const notifyFactory = context._notifyFactory;
+  if (!notifyFactory) return context.notify;
+  if (notifyTiming === "inline") return notifyFactory(scopedUser, targetTenantId);
+  // Still inside the caller's write tx: delivery DB work must not wait for an app-pool slot.
+  const notifyInsideTransaction = (context._notifyInTransactionFactory ?? notifyFactory)(
+    scopedUser,
+    targetTenantId,
+  );
+  const scheduleAfterCommit = context.scheduleAfterCommit;
+  if (!scheduleAfterCommit) return notifyInsideTransaction;
+  return createDeferringNotify({
+    registry: context.registry,
+    tenantId: targetTenantId,
+    notifyAfterCommit: notifyFactory(scopedUser, targetTenantId),
+    notifyNow: notifyInsideTransaction,
+    scheduleAfterCommit,
+  });
+}
+
 // `runner` comes from the caller, which already holds a declared DbRunner —
 // a TenantDb exposes no runner back out to feature code.
 function scopeSeedHookContext(
   context: AppContext,
   targetTenantId: TenantId,
   runner: DbRunner,
+  // The afterCommit sink is snapshotted when it flushes, so a hook scheduled from inside an
+  // afterCommit-phase hook would be dropped: that phase must notify inline.
+  notifyTiming: "deferUntilCommit" | "inline",
 ): AppContext {
   const db = createTenantDb(
     runner,
@@ -142,10 +173,9 @@ function scopeSeedHookContext(
     ? { ...baseUser, tenantId: targetTenantId }
     : undefined;
 
-  const notify =
-    context._notifyFactory && scopedUser
-      ? context._notifyFactory(scopedUser, targetTenantId)
-      : context.notify;
+  const notify = scopedUser
+    ? buildSeedHookNotify(context, scopedUser, targetTenantId, notifyTiming)
+    : context.notify;
 
   const features = context.effectiveFeatures as
     | (((tenantId: TenantId) => ReadonlySet<string>) & {
@@ -188,10 +218,14 @@ export async function fireEntityPostSave(
   const scopedContext =
     target === undefined
       ? hooks.context
-      : scopeSeedHookContext(hooks.context, target.tenantId, target.db);
+      : scopeSeedHookContext(hooks.context, target.tenantId, target.db, "deferUntilCommit");
+  const afterCommitContext =
+    target === undefined
+      ? hooks.context
+      : scopeSeedHookContext(hooks.context, target.tenantId, target.db, "inline");
   await lifecycle.runPostSave(pseudoType, entityData, scopedContext, HookPhases.inTransaction);
   const runAfterCommit = () =>
-    lifecycle.runPostSave(pseudoType, entityData, scopedContext, HookPhases.afterCommit);
+    lifecycle.runPostSave(pseudoType, entityData, afterCommitContext, HookPhases.afterCommit);
   if (scopedContext.scheduleAfterCommit) {
     scopedContext.scheduleAfterCommit(runAfterCommit);
   } else {

package/packages/bundled-features/src/tenant-lifecycle/boot-checks.ts

@@ -27,7 +27,7 @@ function hasTenantOwned(field: unknown): field is ResolvedPiiFlags {
     typeof field === "object" &&
     field !== null &&
     "tenantOwned" in field &&
-    (field as { tenantOwned?: unknown }).tenantOwned === true
+    field.tenantOwned === true
   );
 }
 

package/packages/bundled-features/src/tenant-lifecycle/handlers/cancel-destruction.write.ts

@@ -72,12 +72,13 @@ export const cancelDestructionWrite = defineWriteHandler({
       payload: { cancelledBy: event.user.id },
     });
 
+    const gracePeriodEnd: string | null = null;
     return {
       isSuccess: true as const,
       data: {
         tenantId,
         status: "active" as const,
-        gracePeriodEnd: null as string | null,
+        gracePeriodEnd,
       },
     };
   },