@cosmicdrift/kumiko-samples 0.377.0 → 0.378.0

package/packages/bundled-features/src/template-resolver/handlers/upsert-tenant.write.ts

@@ -1,5 +1,10 @@
 import { defineWriteHandler, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
+import {
+  refuseTemplateEdit,
+  type TemplateEditPolicy,
+  templateEditAccess,
+} from "../template-edit-policy.ts";
 import { resolveTemplateVariables } from "../template-validation.ts";
 import { upsertPayloadSchema } from "./shared.ts";
 import { writeTemplateRow } from "./template-write.ts";
@@ -9,32 +14,36 @@ import { writeTemplateRow } from "./template-write.ts";
 // via publish-Handler. SystemAdmin kann via tenantIdOverride für
 // einen anderen Tenant schreiben (typisch: Plattform-Admin-UI das
 // Tenant-Templates kuratiert).
-export const upsertTenantWrite = defineWriteHandler({
-  name: "upsert-tenant",
-  schema: upsertPayloadSchema.extend({
-    tenantIdOverride: z.string().min(1).optional(),
-    status: z.enum(["draft", "active"]).default("draft"),
-  }),
-  access: { roles: ["TenantAdmin", "SystemAdmin"] },
-  description:
-    "Creates or overwrites a tenant-scoped template override with its variable schema, landing as a draft that only publish makes live (over an active override the draft is stored beside it, the active version keeps being served until publish); it refuses a system-tenant target, which is what upsert-system is for.",
-  handler: async (event, ctx) => {
-    // @cast-boundary engine-payload — override aus Zod-parsed string,
-    // event.user.tenantId schon TenantId-branded; union als TenantId casten
-    // ist legit (override ist UUID-Format-validiert in schema).
-    const tenantId = (event.payload.tenantIdOverride ?? event.user.tenantId) as TenantId;
-    return writeTemplateRow({
-      ctx,
-      user: event.user,
-      tenantId,
-      scope: "tenant",
-      status: event.payload.status,
-      variables: resolveTemplateVariables(
-        ctx.registry,
-        event.payload.slug,
-        event.payload.variableSchema,
-      ),
-      payload: event.payload,
-    });
-  },
-});
+export function makeUpsertTenantWrite(policy: TemplateEditPolicy) {
+  return defineWriteHandler({
+    name: "upsert-tenant",
+    schema: upsertPayloadSchema.extend({
+      tenantIdOverride: z.string().min(1).optional(),
+      status: z.enum(["draft", "active"]).default("draft"),
+    }),
+    access: templateEditAccess(policy.tenantEditable),
+    description:
+      "Creates or overwrites a tenant-scoped template override with its variable schema, landing as a draft that only publish makes live (over an active override the draft is stored beside it, the active version keeps being served until publish); it refuses a system-tenant target, which is what upsert-system is for; a TenantAdmin may write it only for templates the app lists in tenantEditable, otherwise SystemAdmin only.",
+    handler: async (event, ctx) => {
+      const refused = refuseTemplateEdit(policy, event.user, event.payload);
+      if (refused !== null) return refused;
+      // @cast-boundary engine-payload — override is a zod-validated string and
+      // event.user.tenantId is already TenantId-branded; forTenant rejects the
+      // override for non-SystemAdmins.
+      const tenantId = (event.payload.tenantIdOverride ?? event.user.tenantId) as TenantId;
+      return writeTemplateRow({
+        ctx,
+        user: event.user,
+        tenantId,
+        scope: "tenant",
+        status: event.payload.status,
+        variables: resolveTemplateVariables(
+          ctx.registry,
+          event.payload.slug,
+          event.payload.variableSchema,
+        ),
+        payload: event.payload,
+      });
+    },
+  });
+}

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

@@ -1,3 +1,4 @@
+export { isResourceImageContentType } from "../shared/index.ts";
 export {
   createTemplateResolverApi,
   type ResolveRequest,
@@ -8,6 +9,7 @@ export {
 } from "./api.ts";
 export {
   type CompileDocumentBodyOptions,
+  collectDocumentImageVariables,
   collectDocumentResourceKeys,
   compileDocumentBodyToHandlebars,
   toResourceDataUri,
@@ -75,7 +77,7 @@ export {
   isDocumentReferenceName,
   isDocumentResourceKey,
 } from "./document-schema.ts";
-export { createTemplateResolverFeature } from "./feature.ts";
+export { createTemplateResolverFeature, type TemplateResolverOptions } from "./feature.ts";
 export type { LayoutSourceResponse, LayoutSourceRow } from "./handlers/layout-source.query.ts";
 export type {
   OverviewKindGroup,
@@ -126,6 +128,11 @@ export {
   templateResourcesTable,
 } from "./table.ts";
 export { type TemplateBundle, templateBundleSchema } from "./template-bundle.ts";
+export {
+  type TemplateEditPolicy,
+  type TenantEditableTemplate,
+  templateEditAccess,
+} from "./template-edit-policy.ts";
 export {
   isMailTemplateMeta,
   type LayoutTemplateMeta,

package/packages/bundled-features/src/template-resolver/qualified-names.ts

@@ -35,6 +35,7 @@ export const TemplateResolverQueries = {
   preview: "template-resolver:query:preview",
   documentBlocks: "template-resolver:query:document-blocks",
   exportBundle: "template-resolver:query:export-bundle",
+  sendTestStatus: "template-resolver:query:send-test-status",
   // Public pair — anonymous-reachable, kind pinned to text-block.
   bySlug: "template-resolver:query:by-slug",
   byTenant: "template-resolver:query:by-tenant",
@@ -63,6 +64,7 @@ export const TemplateResolverErrors = {
   targetExists: "target_exists",
   systemResourcesNeedSystemTenant: "system_resources_need_system_tenant",
   systemOnlyTemplate: "system_only_template",
+  templateNotTenantEditable: "template_not_tenant_editable",
   bundleLocalesDiffer: "bundle_locales_differ",
   resourceTooLarge: "template_resource_too_large",
   resourceUnsupportedImage: "template_resource_unsupported_image",

package/packages/bundled-features/src/template-resolver/template-edit-policy.ts

@@ -0,0 +1,91 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
+import {
+  type HandlerContext,
+  hasAccess,
+  type RoleAccessRule,
+  type SessionUser,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  AccessDeniedError,
+  type WriteFailure,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+import type { TemplateKind } from "./constants.ts";
+import { TemplateResolverErrors } from "./qualified-names.ts";
+import { type TemplateResourceRow, templateResourcesTable } from "./table.ts";
+import { isSystemAdmin } from "./template-draft.ts";
+
+export type TenantEditableTemplate = {
+  readonly kind: TemplateKind;
+  readonly slug: string;
+  readonly access: RoleAccessRule;
+};
+
+export type TemplateEditPolicy = {
+  readonly tenantEditable: readonly TenantEditableTemplate[];
+};
+
+type EditTarget = { readonly slug: string; readonly kind: string };
+type EditUser = Pick<SessionUser, "roles">;
+
+const SYSTEM_ADMIN_ROLE = "SystemAdmin";
+
+export function templateEditAccess(entries: readonly TenantEditableTemplate[]): RoleAccessRule {
+  const roles = new Set<string>([SYSTEM_ADMIN_ROLE]);
+  for (const entry of entries) {
+    for (const role of entry.access.roles) roles.add(role);
+  }
+  return { roles: [...roles] };
+}
+
+export function mayEditTemplate(
+  policy: TemplateEditPolicy,
+  user: EditUser,
+  target: EditTarget,
+): boolean {
+  if (isSystemAdmin(user)) return true;
+  const entry = policy.tenantEditable.find(
+    (candidate) => candidate.slug === target.slug && candidate.kind === target.kind,
+  );
+  return entry !== undefined && hasAccess(user, entry.access);
+}
+
+export function refuseTemplateEdit(
+  policy: TemplateEditPolicy,
+  user: EditUser,
+  target: EditTarget,
+): WriteFailure | null {
+  if (mayEditTemplate(policy, user, target)) return null;
+  return writeFailure(
+    new AccessDeniedError({
+      i18nKey: "templateResolver.errors.templateNotTenantEditable",
+      details: { reason: TemplateResolverErrors.templateNotTenantEditable },
+    }),
+  );
+}
+
+// Fail closed: a missing row gives a non-SystemAdmin the same refusal as a locked one,
+// so the response never reveals whether an id exists. SystemAdmin keeps the 404.
+export function refuseMissingTemplate(
+  policy: TemplateEditPolicy,
+  user: EditUser,
+): WriteFailure | null {
+  return isSystemAdmin(user) ? null : refuseTemplateEdit(policy, user, { slug: "", kind: "" });
+}
+
+export async function refuseTemplateEditById(
+  db: HandlerContext["db"],
+  policy: TemplateEditPolicy,
+  user: EditUser,
+  tenantId: string,
+  templateId: string,
+): Promise<WriteFailure | null> {
+  if (isSystemAdmin(user)) return null;
+  const row = await fetchOne<TemplateResourceRow>(db, templateResourcesTable, {
+    tenantId,
+    id: templateId,
+  });
+  return row === undefined
+    ? refuseMissingTemplate(policy, user)
+    : refuseTemplateEdit(policy, user, row);
+}

package/packages/bundled-features/src/template-resolver/template-preview.ts

@@ -4,6 +4,7 @@ import {
   type SessionUser,
   type TemplateListVariableDef,
   type TemplateScalarVariableDef,
+  type TemplateVariableDef,
   type TemplateVariables,
   templateVariablesToZod,
 } from "@cosmicdrift/kumiko-framework/engine";
@@ -120,6 +121,12 @@ function sampleList(def: TemplateListVariableDef, labelText: LabelText): Record<
   return rows;
 }
 
+function sampleValueFor(name: string, def: TemplateVariableDef, labelText: LabelText): unknown {
+  // An images variable has no sample: file ids are record data, never preview content.
+  if (def.type === "images") return [];
+  return def.type === "list" ? sampleList(def, labelText) : sampleScalar(name, def, labelText);
+}
+
 // Declared examples win; the fallbacks are deterministic so a preview never differs between calls.
 export function sampleValuesFor(
   variables: TemplateVariables,
@@ -127,8 +134,7 @@ export function sampleValuesFor(
 ): Record<string, unknown> {
   const values: Record<string, unknown> = {};
   for (const [name, def] of Object.entries(variables)) {
-    values[name] =
-      def.type === "list" ? sampleList(def, labelText) : sampleScalar(name, def, labelText);
+    values[name] = sampleValueFor(name, def, labelText);
   }
   return values;
 }

package/packages/bundled-features/src/template-resolver/template-validation.ts

@@ -65,6 +65,7 @@ const scalarVariableSchema = z.discriminatedUnion("type", [
 
 const variableDefSchema = z.union([
   scalarVariableSchema,
+  z.object({ ...variableCommon, type: z.literal("images") }),
   z.object({
     ...variableCommon,
     type: z.literal("list"),
@@ -126,17 +127,24 @@ function listItemFields(
   return def?.type === "list" ? def.item : {};
 }
 
+// An images variable holds file ids: as text it would leak them, so only an images block
+// (and a condition on its presence) may name it.
 function isKnownName(
   name: string,
   scope: PlaceholderScope,
   itemFields: Readonly<Record<string, unknown>>,
+  allowImages = false,
 ): Resolution {
   const { variables } = scope;
   const root = rootName(name);
   // Declared variables and item fields are scalars: a dotted path under one never renders a value.
   if (Object.hasOwn(itemFields, name)) return { known: true, used: "" };
   if (scope.systemPlaceholders.has(root)) return { known: true, used: "" };
-  if (Object.hasOwn(variables, name)) return { known: true, used: name };
+  if (Object.hasOwn(variables, name)) {
+    return variables[name]?.type === "images" && !allowImages
+      ? { known: false, used: "" }
+      : { known: true, used: name };
+  }
   return { known: false, used: "" };
 }
 
@@ -144,8 +152,9 @@ function recordName(
   name: string,
   itemFields: Readonly<Record<string, unknown>>,
   scope: PlaceholderScope,
+  allowImages = false,
 ) {
-  const resolution = isKnownName(name, scope, itemFields);
+  const resolution = isKnownName(name, scope, itemFields, allowImages);
   if (!resolution.known) scope.unknown.add(name);
   else if (resolution.used !== "") scope.used.add(resolution.used);
 }
@@ -154,10 +163,18 @@ function enclosingEachName(element: ScanElement): string | null {
   return element.closest("tr[data-each]")?.getAttribute("data-each") ?? null;
 }
 
-const NAME_ATTRIBUTE_BY_TAG: Readonly<Record<string, string>> = {
-  span: "data-variable",
-  div: "data-steps",
-};
+function nameAttributeOf(element: ScanElement): string | undefined {
+  const tag = element.tagName.toLowerCase();
+  if (tag === "span") return "data-variable";
+  if (tag !== "div") return undefined;
+  return element.hasAttribute("data-images") ? "data-images" : "data-steps";
+}
+
+function recordImagesName(name: string, scope: PlaceholderScope): void {
+  const def = Object.hasOwn(scope.variables, name) ? scope.variables[name] : undefined;
+  if (def?.type === "images") scope.used.add(name);
+  else scope.unknown.add(name);
+}
 
 function scanRepeatRows(root: ScanElement, scope: PlaceholderScope): void {
   for (const element of Array.from(root.querySelectorAll("tr[data-each]"))) {
@@ -174,18 +191,22 @@ function scanConditions(root: ScanElement, scope: PlaceholderScope): void {
       scope.variables,
       enclosingEachName(conditionScopeElement(element)),
     );
-    recordName(element.getAttribute(DOCUMENT_CONDITION_ATTRIBUTE) ?? "", itemFields, scope);
+    recordName(element.getAttribute(DOCUMENT_CONDITION_ATTRIBUTE) ?? "", itemFields, scope, true);
   }
 }
 
 function scanReferences(root: ScanElement, scope: PlaceholderScope): void {
   for (const element of Array.from(
-    root.querySelectorAll("span[data-variable], div[data-steps], a[href], img[data-resource]"),
+    root.querySelectorAll(
+      "span[data-variable], div[data-steps], div[data-images], a[href], img[data-resource]",
+    ),
   )) {
     const itemFields = listItemFields(scope.variables, enclosingEachName(element));
     const tag = element.tagName.toLowerCase();
-    const nameAttribute = NAME_ATTRIBUTE_BY_TAG[tag];
-    if (nameAttribute !== undefined) {
+    const nameAttribute = nameAttributeOf(element);
+    if (nameAttribute === "data-images") {
+      recordImagesName(element.getAttribute(nameAttribute) ?? "", scope);
+    } else if (nameAttribute !== undefined) {
       recordName(element.getAttribute(nameAttribute) ?? "", itemFields, scope);
     } else if (tag === "a") {
       const href = element.getAttribute("href") ?? "";

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

@@ -5,6 +5,7 @@ import { Dropcursor, Gapcursor, Placeholder, UndoRedo } from "@tiptap/extensions
 import type { Node as ProseMirrorNode } from "@tiptap/pm/model";
 import {
   DocumentButton,
+  DocumentImages,
   DocumentPageBreak,
   DocumentResource,
   DocumentSteps,
@@ -23,6 +24,7 @@ export type DocumentEditorLabels = {
   readonly pageBreak: string;
   readonly button?: string;
   readonly steps?: string;
+  readonly images?: string;
   /** Canvas block label of an image, e.g. "Image · inline". */
   readonly imageBlock?: string;
   readonly variableLabels?: Readonly<Record<string, string>>;
@@ -206,6 +208,31 @@ function createStepsView(labels: DocumentEditorLabels): NodeViewRenderer {
   };
 }
 
+// A sketch only: the photos are record data, known at render time.
+function createImagesView(labels: DocumentEditorLabels): NodeViewRenderer {
+  return ({ node }) => {
+    const dom = createElementWithClass(
+      "div",
+      "relative my-3 rounded border border-dashed border-input px-3 pb-3 pt-4",
+    );
+    dom.setAttribute(DOCUMENT_BLOCK_ATTRIBUTE, "");
+    dom.contentEditable = "false";
+    const variable = String(node.attrs["variable"]);
+    const variableLabels = labels.variableLabels ?? {};
+    const variableLabel = Object.hasOwn(variableLabels, variable)
+      ? variableLabels[variable]
+      : undefined;
+    dom.append(createBlockLabel(`${labels.images ?? "Photos"} · ${variableLabel ?? variable}`));
+    const grid = createElementWithClass("div", "grid grid-cols-2 gap-1.5");
+    grid.append(
+      createElementWithClass("div", "h-12 rounded bg-muted"),
+      createElementWithClass("div", "h-12 rounded bg-muted"),
+    );
+    dom.append(grid);
+    return { dom };
+  };
+}
+
 // Replaced by name, not appended: the schema must keep exactly one node per
 // name, and only the editor view differs from the shared document schema.
 export function createDocumentEditorExtensions(labels: DocumentEditorLabels): Extensions {
@@ -224,6 +251,8 @@ export function createDocumentEditorExtensions(labels: DocumentEditorLabels): Ex
           : extension;
       case DocumentSteps.name:
         return DocumentSteps.extend({ addNodeView: () => createStepsView(labels) });
+      case DocumentImages.name:
+        return DocumentImages.extend({ addNodeView: () => createImagesView(labels) });
       case DocumentPageBreak.name:
         return DocumentPageBreak.extend({
           addNodeView: () => createPageBreakView(labels.pageBreak),

package/packages/bundled-features/src/template-resolver/web/document-tiptap-editor.tsx

@@ -25,6 +25,7 @@ import {
   Bold as BoldIcon,
   Braces,
   ChevronDown,
+  GalleryThumbnails,
   Image as ImageIcon,
   Italic as ItalicIcon,
   Link as LinkIcon,
@@ -72,7 +73,15 @@ function previewsKey(previews: Readonly<Record<string, DocumentResourcePreview>>
     .join("\n");
 }
 
-type PanelKind = "link" | "placeholder" | "image" | "button" | "repeat" | "align" | "steps";
+type PanelKind =
+  | "link"
+  | "placeholder"
+  | "image"
+  | "button"
+  | "repeat"
+  | "align"
+  | "steps"
+  | "images";
 
 // Blocks that stay in the canvas toolbar; the rest moves into the overflow menu.
 const CANVAS_INLINE_BLOCKS: readonly DocumentToolbarBlock[] = ["image", "table"];
@@ -83,6 +92,7 @@ const BLOCK_PANEL: Partial<Record<DocumentToolbarBlock, PanelKind>> = {
   repeat: "repeat",
   align: "align",
   steps: "steps",
+  images: "images",
 };
 
 const ALIGNMENT_ICONS: Record<DocumentTextAlignment, ReactNode> = {
@@ -392,7 +402,11 @@ function InsertPanel({
   };
 
   const needsVariables =
-    kind === "button" || kind === "repeat" || kind === "placeholder" || kind === "steps";
+    kind === "button" ||
+    kind === "repeat" ||
+    kind === "placeholder" ||
+    kind === "steps" ||
+    kind === "images";
   const noVariables = needsVariables && selectable.length === 0;
   const idPrefix = `${editorId}-panel`;
 
@@ -498,6 +512,16 @@ function InsertPanel({
           onChange={setChosenName}
         />
       )}
+      {kind === "images" && !noVariables && (
+        <NameSelect
+          id={`${idPrefix}-images-variable`}
+          label={t("template-resolver.documentEditor.imagesVariable")}
+          names={selectable}
+          labels={variableLabels}
+          value={selectedName}
+          onChange={setChosenName}
+        />
+      )}
       {kind === "steps" && !noVariables && (
         <>
           <NameSelect
@@ -551,6 +575,10 @@ function InsertPanel({
           {...(kind === "repeat" &&
             !noVariables && { onInsert: () => insertAndClose(repeatTableContent(selectedName)) })}
           {...(kind === "steps" && !noVariables && { onInsert: submitSteps })}
+          {...(kind === "images" &&
+            !noVariables && {
+              onInsert: () => insertAndClose({ type: "images", attrs: { variable: selectedName } }),
+            })}
         />
       </div>
     </div>
@@ -563,7 +591,8 @@ export default function DocumentTiptapEditor({
   onChange,
   variables,
   readOnly,
-  blocks = MAIL_DOCUMENT_BLOCKS,
+  blocks: configuredBlocks = MAIL_DOCUMENT_BLOCKS,
+  imageVariables = NO_NAMES,
   variableLabels = NO_LABELS,
   systemVariables = NO_NAMES,
   resourcePreviews = NO_PREVIEWS,
@@ -581,6 +610,11 @@ export default function DocumentTiptapEditor({
   const canvas = chrome === "canvas";
   const compact = toolbar === "compact" && !canvas;
   const hosted = toolbarHost !== undefined;
+  // A photo block needs an images variable to bind to; without one the button would open an empty panel.
+  const blocks =
+    imageVariables.length === 0
+      ? configuredBlocks.filter((block) => block !== "images")
+      : configuredBlocks;
 
   const placeholderLabel = t("template-resolver.documentEditor.placeholder");
   const imageLabel = t("template-resolver.documentEditor.image");
@@ -588,6 +622,7 @@ export default function DocumentTiptapEditor({
   const pageBreakLabel = t("template-resolver.documentEditor.pageBreak");
   const buttonLabel = t("template-resolver.documentEditor.button");
   const stepsLabel = t("template-resolver.documentEditor.steps");
+  const imagesLabel = t("template-resolver.documentEditor.images");
   const stableLabels = useStableByKey(variableLabels, JSON.stringify(variableLabels));
   const stableSystem = useStableByKey(systemVariables, systemVariables.join("\n"));
   const stablePreviews = useStableByKey(resourcePreviews, previewsKey(resourcePreviews));
@@ -599,6 +634,7 @@ export default function DocumentTiptapEditor({
         pageBreak: pageBreakLabel,
         button: buttonLabel,
         steps: stepsLabel,
+        images: imagesLabel,
         imageBlock: imageBlockLabel,
         variableLabels: stableLabels,
         systemVariables: stableSystem,
@@ -612,6 +648,7 @@ export default function DocumentTiptapEditor({
       pageBreakLabel,
       buttonLabel,
       stepsLabel,
+      imagesLabel,
       stableLabels,
       stableSystem,
       stablePreviews,
@@ -731,6 +768,7 @@ export default function DocumentTiptapEditor({
     pageBreak: { label: pageBreakLabel, icon: <Scissors size={16} /> },
     align: { label: t("template-resolver.documentEditor.align"), icon: <AlignLeft size={16} /> },
     steps: { label: stepsLabel, icon: <ListChecks size={16} /> },
+    images: { label: imagesLabel, icon: <GalleryThumbnails size={16} /> },
   };
 
   const repeatTable = activeState?.repeatTable ?? null;
@@ -1058,7 +1096,7 @@ export default function DocumentTiptapEditor({
       editor={editor}
       editorId={id}
       kind={openPanel}
-      variables={variables}
+      variables={openPanel === "images" ? imageVariables : variables}
       variableLabels={stableLabels}
       onClose={() => setOpenPanel(null)}
     />

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

@@ -22,6 +22,8 @@ export type DocumentEditorChrome = "default" | "canvas";
 
 export type DocumentEditorProps = ContentEditorProps & {
   readonly blocks?: readonly DocumentToolbarBlock[];
+  /** Names of the template's images variables; the photo block offers exactly these and is hidden without any. */
+  readonly imageVariables?: readonly string[];
   /** 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>>;

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

@@ -43,6 +43,8 @@ export const defaultTranslations: TranslationsByLocale = {
     "template-resolver.documentEditor.removeLink": "Remove link",
     "template-resolver.documentEditor.repeat": "Repeat",
     "template-resolver.documentEditor.repeatList": "List to repeat",
+    "template-resolver.documentEditor.images": "Photos",
+    "template-resolver.documentEditor.imagesVariable": "Photos from",
     "template-resolver.documentEditor.steps": "Steps",
     "template-resolver.documentEditor.stepsVariable": "Current step from",
     "template-resolver.documentEditor.stepsList": "Steps, separated by commas (value=label)",
@@ -58,6 +60,8 @@ export const defaultTranslations: TranslationsByLocale = {
     "template-resolver.editor.saving": "Saving…",
     "template-resolver.editor.created": "Created.",
     "template-resolver.editor.saved": "Saved.",
+    "templateResolver.errors.document.imagesBlockPdfOnly":
+      "Photo blocks are only allowed in PDF documents.",
     "templateResolver.errors.document.buttonHrefNotPlaceholder":
       "The button target “{detail}” must be a placeholder.",
     "templateResolver.errors.document.disallowedLinkHref":
@@ -122,6 +126,8 @@ export const defaultTranslations: TranslationsByLocale = {
     "templateResolver.errors.noDraft": "There is no draft to discard.",
     "templateResolver.errors.systemOnlyTemplate":
       "Only the platform maintains this template; it cannot be overridden per tenant.",
+    "templateResolver.errors.templateNotTenantEditable":
+      "Only the platform may edit this template.",
     "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":

package/samples/apps/ui-walkthrough/src/app/help-action.tsx

@@ -0,0 +1,37 @@
+import { useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { Drawer } from "@cosmicdrift/kumiko-renderer/web";
+import { CircleHelp } from "lucide-react";
+import { type ReactNode, useState } from "react";
+
+// A non-modal side panel: the screen behind stays usable and narrows instead of being covered.
+export function HelpAction(): ReactNode {
+  const t = useTranslation();
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <button
+        type="button"
+        data-testid="help-action"
+        aria-label={t("tasks.help.label")}
+        aria-pressed={open}
+        onClick={() => setOpen((current) => !current)}
+        className="inline-flex size-9 items-center justify-center rounded-md border border-border bg-card text-foreground hover:bg-accent"
+      >
+        <CircleHelp className="h-4 w-4" aria-hidden="true" />
+      </button>
+      <Drawer
+        open={open}
+        onOpenChange={setOpen}
+        side="right"
+        modal={false}
+        belowHeader
+        width={360}
+        title={t("tasks.help.label")}
+        description={t("tasks.help.description")}
+        testId="help-drawer"
+      >
+        <p className="py-2 text-sm text-muted-foreground">{t("tasks.help.body")}</p>
+      </Drawer>
+    </>
+  );
+}

package/samples/apps/ui-walkthrough/src/app/seed-templates.ts

@@ -31,6 +31,7 @@ import {
   SYSTEM_INVOICE_DOCUMENTS,
   SYSTEM_INVOICE_ISSUED,
   SYSTEM_PDF_LAYOUT,
+  SYSTEM_PROPERTY_EXPOSE,
   SYSTEM_TENANCY_CERTIFICATE,
   SYSTEM_TERMS_CHANGED,
   TENANT_INVOICE_OVERRIDES,
@@ -168,6 +169,7 @@ export const seedTemplates: SeedFn = async (stack) => {
   await upsertSystem(SYSTEM_INVOICE_ISSUED);
   await upsertSystem(SYSTEM_TERMS_CHANGED);
   for (const document of SYSTEM_INVOICE_DOCUMENTS) await upsertSystem(document);
+  await upsertSystem(SYSTEM_PROPERTY_EXPOSE);
   const certificate = await upsertSystem(SYSTEM_TENANCY_CERTIFICATE);
   await stack.http.writeOk(
     TemplateResolverHandlers.archiveSystem,

package/samples/apps/ui-walkthrough/src/app/shell.tsx

@@ -14,6 +14,7 @@ import {
   SidebarBrand,
   ThemeMenuItem,
   ThemeToggle,
+  useNav,
   useTranslation,
 } from "@cosmicdrift/kumiko-renderer/web";
 import { MoonStar, Sun } from "lucide-react";
@@ -25,8 +26,10 @@ import {
   NORDLICHT_TENANT_ID,
   NORDLICHT_TENANT_NAME,
 } from "./auth-constants";
+import { HelpAction } from "./help-action";
 
 const APP_NAME = "Kumiko Walkthrough";
+const HELP_SCREEN_ID = "vehicle-edit";
 
 const tenantName = (tenantId: string): string => {
   if (tenantId === DEV_TENANT_ID) return "Dev Tenant";
@@ -49,6 +52,7 @@ export function AppShell({
 }): ReactNode {
   const t = useTranslation();
   const session = useSession();
+  const nav = useNav();
   // Without the user the shell hides role-gated navs and KumikoScreen denies role-gated screens.
   const user = session.user !== null ? { id: session.user.id, roles: session.roles } : undefined;
   return (
@@ -58,6 +62,8 @@ export function AppShell({
       {...(user !== undefined && { user })}
       headerActions={
         <>
+          {/* Only here: the editor screens need the header width for their own actions. */}
+          {nav.route?.screenId === HELP_SCREEN_ID && <HelpAction />}
           <AssistantAction />
           <ThemeToggle />
         </>