@templatical/editor 0.26.2 → 0.27.0

package/dist/index.d.ts

@@ -3,12 +3,14 @@ import { BlockDefaults } from '@templatical/types';
 import type { CollaborationConfig } from '@templatical/types';
 import { ColorsConfig } from '@templatical/types';
 import type { CommentEvent } from '@templatical/types';
+import type { CommentsProvider } from '@templatical/types';
 import { ComputedRef } from 'vue';
 import { createLocalStorageSavedBlocksProvider } from '@templatical/core';
 import type { CustomBlock } from '@templatical/types';
 import { CustomBlockDefinition } from '@templatical/types';
 import { CustomFont } from '@templatical/types';
 import { DisplayConditionsConfig } from '@templatical/types';
+import type { EditorUser } from '@templatical/types';
 import { FontsConfig } from '@templatical/types';
 import { LintOptions } from '@templatical/quality';
 import { LocalStorageSavedBlocksOptions } from '@templatical/core';
@@ -21,20 +23,41 @@ import type { MediaRequestContext } from '@templatical/media-library';
 import type { MediaResult } from '@templatical/types';
 import { MergeTagsConfig } from '@templatical/types';
 import { Ref } from 'vue';
+import { RenderPayload } from '@templatical/types';
+import { RenderProvider } from '@templatical/types';
 import type { ResolvePreview } from '@templatical/types';
 import { SavedBlock } from '@templatical/types';
 import { SavedBlocksListParams } from '@templatical/types';
 import { SavedBlocksProvider } from '@templatical/types';
-import { SaveResult } from '@templatical/types';
 import { Template } from '@templatical/types';
 import { TemplateContent } from '@templatical/types';
 import { TemplateDefaults } from '@templatical/types';
+import { TemplatePatch } from '@templatical/types';
+import { TemplatesProvider } from '@templatical/types';
 import { TestEmailPayload } from '@templatical/types';
 import { TestEmailProvider } from '@templatical/types';
 import { ThemeOverrides } from '@templatical/types';
 import { UiTheme } from '@templatical/types';
+import type { VersionHistoryProvider } from '@templatical/types';
 import { ViewportSize } from '@templatical/types';
 
+/**
+ * How often the editor's single debounced tick fires, and whether it saves.
+ *
+ * `true` / `false` turn autosave on and off at the default cadence; the object
+ * form turns it on and sets the cadence in one key. One key rather than a
+ * `boolean` plus a separate `autoSaveDebounce`, so there is no combination —
+ * `autoSave: false, autoSaveDebounce: 500` — that reads as configured but does
+ * nothing.
+ *
+ * The debounce governs `onChange` too: both ride one `useAutoSave` instance so
+ * the notification and the save cannot drift apart, and so both inherit the
+ * pause-during-undo/redo behaviour `useEditorCore` wires around it.
+ */
+declare type AutoSaveConfig = boolean | {
+    debounce?: number;
+};
+
 export { BlockDefaults }
 
 export { ColorsConfig }
@@ -54,9 +77,42 @@ export declare interface EditorCapabilities {
     ai?: {
         isFeatureEnabled(feature: string): boolean;
     };
+    /**
+     * Present only when a `CommentsProvider` **and** a `user` are configured — via
+     * `init({ comments, user })`, or in Cloud whenever the plan grants `commenting`
+     * (its `user` comes from the JWT).
+     */
     comments?: {
         getBlockCount(blockId: string): number;
         openForBlock(blockId: string): void;
+        /**
+         * Whether the block exists in the **stored** template. A comment is anchored
+         * server-side, so filtering to a block that only exists on the canvas has
+         * nothing to show — the panel says so rather than rendering an empty list.
+         *
+         * Always `true` for a store that accepts any anchor; Cloud is what supplies a
+         * real answer.
+         */
+        isBlockSaved(blockId: string): boolean;
+        /**
+         * Whether the feature is usable right now. Reactive for the same reason as
+         * `savedBlocks.isAvailable`, plus one of its own: with no `user` there is
+         * nobody to attribute a comment to, so the feature reports itself unavailable
+         * rather than writing an anonymous one.
+         */
+        isAvailable: ComputedRef<boolean>;
+        /** Open threads — the count badge on the header trigger. */
+        unresolvedCount: ComputedRef<number>;
+        /**
+         * Which mutations the provider supplied — `false` instead of a function
+         * withholds one. Shared UI hides the corresponding affordance: with all four
+         * false the review is read-only (threads readable, jump-to-block working, no
+         * way to add, edit, delete or resolve).
+         */
+        canCreate: ComputedRef<boolean>;
+        canUpdate: ComputedRef<boolean>;
+        canDelete: ComputedRef<boolean>;
+        canResolve: ComputedRef<boolean>;
     };
     /**
      * Present only when a `SavedBlocksProvider` is configured — in OSS via
@@ -108,6 +164,81 @@ export declare interface EditorCapabilities {
      * `init({ testEmail })`, in Cloud whenever cloud mode is active (or when a
      * consumer supplied their own sender to `initCloud()`).
      */
+    /**
+     * Present only when a `TemplatesProvider` is configured — in OSS via
+     * `init({ templates })`.
+     *
+     * Everything the header needs to render the template's identity and its save
+     * state, so the same chrome works over any storage backend.
+     */
+    templates?: {
+        /**
+         * Persist now. Fire-and-forget: the outcome lands in {@link status}. A no-op
+         * while a save is running, without a loaded template, or when the provider
+         * withheld `save`.
+         */
+        save(): void;
+        /**
+         * Commit an inline rename and persist it. Empty names and no-change commits
+         * are ignored.
+         */
+        rename(name: string): void;
+        /** The loaded template's name, `undefined` when unnamed or not loaded. */
+        name: ComputedRef<string | undefined>;
+        /**
+         * When the stored template was last written, for the header's relative
+         * label. `updatedAt` when the store supplies it, otherwise `createdAt`;
+         * `null` when it supplies neither, which renders no line at all. `kind` is
+         * what picks the "Updated"/"Created" wording.
+         */
+        timestamp: ComputedRef<{
+            iso: string;
+            kind: "updatedAt" | "createdAt";
+        } | null>;
+        /** Whether `create()` or `load()` has resolved — nothing to save until then. */
+        hasTemplate: ComputedRef<boolean>;
+        isSaving: ComputedRef<boolean>;
+        /** Drives the three-state status indicator. */
+        status: Ref<"idle" | "saved" | "error">;
+        errorMessage: Ref<string>;
+        /**
+         * Which mutations the provider supplied — `false` instead of a function
+         * withholds one. With `canSave` false the save button *and* the status
+         * indicator disappear, and the name becomes read-only: there is nowhere for
+         * a change to go.
+         */
+        canCreate: ComputedRef<boolean>;
+        canSave: ComputedRef<boolean>;
+        /**
+         * Whether the feature is usable right now. Reactive for the same reason as
+         * `savedBlocks.isAvailable`.
+         */
+        isAvailable: ComputedRef<boolean>;
+    };
+    /**
+     * Present only when a `VersionHistoryProvider` is configured — via
+     * `init({ versionHistory })` or `initCloud({ versionHistory })`.
+     */
+    versionHistory?: {
+        /** Re-read the list from the provider. A no-op before a template exists. */
+        refresh(): void;
+        /** True while a past version is on the canvas instead of the user's work. */
+        isPreviewing: ComputedRef<boolean>;
+        /** Nothing has a history until `create()` or `load()` has resolved. */
+        hasTemplate: ComputedRef<boolean>;
+        /**
+         * Whether the feature is usable right now. Reactive for the same reason as
+         * `savedBlocks.isAvailable`.
+         */
+        isAvailable: ComputedRef<boolean>;
+        /**
+         * Which mutations the provider supplied — `false` instead of a function
+         * withholds one. With `canRestore` false the history is browsable and
+         * previewable but the Restore action does not render.
+         */
+        canCreate: ComputedRef<boolean>;
+        canRestore: ComputedRef<boolean>;
+    };
     testEmail?: {
         /** Open the send dialog. A no-op while {@link isAvailable} is false. */
         open(): void;
@@ -157,6 +288,35 @@ export declare type HtmlBlockPreviewConfig = boolean | {
 
 export declare function init(config: TemplaticalEditorConfig): Promise<TemplaticalEditor>;
 
+/**
+ * Mount the editor against Templatical Cloud.
+ *
+ * **This is `init()` with Cloud's adapters filled in**, and deliberately nothing
+ * more. Templates, rendering and version history are providers, so Cloud's entry
+ * point is adapter wiring rather than a second editor:
+ *
+ * 1. Build the auth manager and complete the handshake.
+ * 2. Health-check the API, and fetch the plan config.
+ * 3. Build Cloud's adapters over that auth manager.
+ * 4. Delegate to `init()`.
+ *
+ * A failure in steps 1–2 **rejects**, rather than mounting an editor that shows
+ * an error overlay. That is the one place the wrapper is genuinely not `init()`:
+ * `init()` cannot fail after it mounts, and OSS should not grow the ability. A
+ * session that dies *later* — an auth refresh that cannot renew the token — does
+ * still surface as an overlay, because by then there is an editor to cover.
+ *
+ * `templates`, `versionHistory` and `comments` are the three keys `initCloud()`
+ * refuses: all are keyed to a template id Cloud issued, which also anchors
+ * collaboration, AI rewrite, scoring and the server-side export. A store Cloud
+ * never issued ids for would degrade all of them silently. Everything else —
+ * `render`, `savedBlocks`, `testEmail`, `resolvePreview` — is the same key with the
+ * same type on both entry points, so upgrading an OSS integration is a deletion.
+ *
+ * `user` is not a key either: Cloud signs comment writes against the auth token's
+ * `user` claim, so it fills `init({ user })` from there rather than letting a
+ * browser name someone else.
+ */
 export declare function initCloud(config: TemplaticalCloudEditorConfig): Promise<TemplaticalCloudEditor>;
 
 /** Check if a locale has cloud translations (matched by exact locale, then base). */
@@ -178,6 +338,10 @@ export { MergeTagsConfig }
 /** Function type for media browser requests, used by both OSS and Cloud editors. */
 export declare type OnRequestMedia = (context?: MediaRequestContext) => Promise<MediaResult | null>;
 
+export { RenderPayload }
+
+export { RenderProvider }
+
 /**
  * Display-only resolver for image `src` values (`config.resolveImageUrl`,
  * #415). Maps a canonical src (e.g. a plain file name like `logo.png`) to a
@@ -193,26 +357,32 @@ export { SavedBlocksListParams }
 
 export { SavedBlocksProvider }
 
-export { SaveResult }
-
 export { Template }
 
 export { TemplateContent }
 
 export { TemplateDefaults }
 
+export { TemplatePatch }
+
+export { TemplatesProvider }
+
 /**
- * Cloud editor does not expose `toMjml` or `renderCustomBlock`: the cloud
- * backend performs MJML conversion server-side with additional processing
- * (e.g., signed image URLs, attachment handling) that isn't available client
- * side. Use the cloud `save()` flow to persist content; the backend handles
- * MJML/HTML export from there.
+ * `initCloud()` returns the **same** editor `init()` does.
+ *
+ * That is the point rather than a tidy-up: Cloud is a set of provider
+ * implementations behind the same interfaces a consumer would implement, so if
+ * the two entry points still returned different shapes, the claim would be
+ * false. It also means moving between them is a config change and never a
+ * rewrite of the calling code.
+ *
+ * Three cloud-only members went with the convergence: `setThemeOverrides`
+ * (`config.theme` is applied at init on both entry points, and the entitlement
+ * that gated changing it later is gone), and `sendTestEmail` (the shared dialog
+ * is the supported path). `create()` takes `init()`'s `{ name?, content? }`
+ * input object rather than a bare `TemplateContent`.
  */
-export declare interface TemplaticalCloudEditor extends TemplaticalEditorBase {
-    create(content?: TemplateContent): Promise<Template>;
-    load(templateId: string): Promise<Template>;
-    save(): Promise<SaveResult>;
-}
+export declare type TemplaticalCloudEditor = TemplaticalEditor;
 
 export declare interface TemplaticalCloudEditorConfig {
     container: string | HTMLElement;
@@ -272,6 +442,19 @@ export declare interface TemplaticalCloudEditorConfig {
      * @default true
      */
     smallScreenNotice?: boolean;
+    /**
+     * Show the template's name in the header, inline-editable. Defaults to `true`.
+     *
+     * Set to `false` when your store has no name column, or when your own chrome
+     * owns the name. Hides the field only — `create({ name })`, `setName()` and the
+     * `name` in each save patch keep working, so a headless caller or your own UI
+     * can still manage names.
+     *
+     * Without a `templates` provider the header renders no name field either way.
+     *
+     * @default true
+     */
+    templateNameField?: boolean;
     ai?: AiConfig | false;
     commenting?: boolean;
     collaboration?: CollaborationConfig;
@@ -293,8 +476,13 @@ export declare interface TemplaticalCloudEditorConfig {
      * leaving it exactly as-is (to keep your own) — never rewriting it.
      */
     savedBlocks?: boolean | SavedBlocksProvider;
-    autoSave?: boolean;
-    autoSaveDebounce?: number;
+    /**
+     * Save automatically, debounced. **The same key and the same type as
+     * `init()`** — `true`/`false`, or `{ debounce }` to set the cadence in one
+     * key. Unlike OSS it defaults to *on*, because a Cloud session always has a
+     * store to save to.
+     */
+    autoSave?: AutoSaveConfig;
     mergeTags?: MergeTagsConfig;
     logicTags?: LogicTagsConfig;
     displayConditions?: DisplayConditionsConfig;
@@ -331,7 +519,20 @@ export declare interface TemplaticalCloudEditorConfig {
      */
     colors?: ColorsConfig;
     onChange?: (content: TemplateContent) => void;
-    onSave?: (result: SaveResult) => void;
+    /**
+     * Called whenever the editor's unsaved-changes state flips. **The same key and
+     * the same type as `init()`'s** — one editor, one set of keys.
+     */
+    onDirtyChange?: (isDirty: boolean) => void;
+    /**
+     * Warn before closing the tab with unsaved changes. On by default, since a
+     * Cloud session always has a store to save to. Set to `false` to own the
+     * prompt yourself; it can never cover client-side route changes either way,
+     * which is what {@link onDirtyChange} is for.
+     *
+     * @default true
+     */
+    unsavedChangesGuard?: boolean;
     onCreate?: (template: Template) => void;
     onLoad?: (template: Template) => void;
     onError?: (error: Error) => void;
@@ -383,11 +584,33 @@ export declare interface TemplaticalCloudEditorConfig {
 
 export declare interface TemplaticalEditor extends TemplaticalEditorBase {
     /**
-     * Render the current template to an MJML string. Resolves custom blocks
-     * via the editor's internal block registry. Throws if the optional
-     * `@templatical/renderer` package is not installed.
+     * Persist the current content as a new template through the configured
+     * `templates` provider, and make the result the editor's template.
+     *
+     * `input.content`, when given, replaces the editor's content first. Always
+     * present on the type; rejects with an explanatory error when no provider is
+     * configured or when the provider set `create: false` — the same convention as
+     * {@link toMjml}.
      */
-    toMjml(): Promise<string>;
+    create(input?: {
+        name?: string;
+        content?: TemplateContent;
+    }): Promise<Template>;
+    /** Load a template by id and make it the editor's content. */
+    load(templateId: string): Promise<Template>;
+    /**
+     * Persist the loaded template — name and content, as one patch. Rejects when
+     * no provider is configured, when the provider set `save: false`, or when no
+     * template has been created or loaded yet.
+     */
+    save(): Promise<Template>;
+    /**
+     * Whether there are edits the editor knows aren't persisted. Cleared by a
+     * successful `save()` / `create()` / `load()`.
+     *
+     * Read it in a router guard; `onDirtyChange` is the push-based counterpart.
+     */
+    isDirty(): boolean;
     /**
      * Render a single custom block to its HTML representation, using the
      * registered custom block definition's template and the block's current
@@ -411,6 +634,25 @@ declare interface TemplaticalEditorBase {
     setContent(content: TemplateContent): void;
     setTheme(theme: UiTheme): void;
     unmount(): void;
+    /**
+     * Render the current template to MJML.
+     *
+     * Resolves `render.toMjml` first when a `render` provider supplies it, then the
+     * bundled `@templatical/renderer` (which resolves custom blocks through the
+     * editor's own registry). Rejects with a clear error when neither is available —
+     * i.e. no provider method *and* the optional `@templatical/renderer` peer isn't
+     * installed.
+     */
+    toMjml(): Promise<string>;
+    /**
+     * Render the current template to sending-ready HTML.
+     *
+     * Resolves `render.toHtml` first, then `toMjml()`'s output through
+     * `render.compileMjml`. **Requires one of the two** — the SDK bundles no MJML
+     * compiler, so with no `render` provider this always rejects, and the error says
+     * which method to add.
+     */
+    toHtml(): Promise<string>;
 }
 
 export declare interface TemplaticalEditorConfig {
@@ -449,8 +691,158 @@ export declare interface TemplaticalEditorConfig {
      */
     shadowDom?: boolean;
     onChange?: (content: TemplateContent) => void;
-    onSave?: (content: TemplateContent) => void;
     onError?: (error: Error) => void;
+    /**
+     * Called whenever the editor's unsaved-changes state flips — `true` on the
+     * first edit after a save, `false` once a save completes.
+     *
+     * Works with or without a `templates` provider, because the editor's own
+     * `beforeunload` guard cannot cover SPA route changes: an embedded editor's
+     * consumer has to guard their router themselves, and this is what they guard
+     * it with.
+     */
+    onDirtyChange?: (isDirty: boolean) => void;
+    /**
+     * Storage backend for **the template itself** — the save/load lifecycle around
+     * whatever is on the canvas.
+     *
+     * The editor owns the header's name field, save button and save-status
+     * indicator, the Cmd+S shortcut, autosave and the unsaved-changes guard; you
+     * own persistence. Three methods:
+     *
+     * ```ts
+     * const editor = await init({
+     *   container,
+     *   templates: {
+     *     load: (id) => fetch(`/api/templates/${id}`).then((r) => r.json()),
+     *     create: (input) =>
+     *       fetch("/api/templates", {
+     *         method: "POST",
+     *         headers: { "Content-Type": "application/json" },
+     *         body: JSON.stringify(input),
+     *       }).then((r) => r.json()),
+     *     save: (id, patch) =>
+     *       fetch(`/api/templates/${id}`, {
+     *         method: "PATCH",
+     *         headers: { "Content-Type": "application/json" },
+     *         body: JSON.stringify(patch),
+     *       }).then((r) => r.json()),
+     *   },
+     * });
+     *
+     * await editor.load("tpl_123");
+     * ```
+     *
+     * **Omitted by default.** With no provider the feature is entirely off — no
+     * name field, no save button, no status indicator — and `create()` / `load()` /
+     * `save()` reject with an explanatory error. Persist the content yourself from
+     * `onChange` instead; Cmd+S then flushes that notification immediately rather
+     * than waiting out the debounce.
+     *
+     * Opening a template is deliberately imperative: there is no `templateId`
+     * config key and no in-editor template browser, because choosing which
+     * template to open belongs to your application.
+     */
+    templates?: TemplatesProvider;
+    /**
+     * Rendering backend — how the template becomes MJML, and how MJML becomes the
+     * HTML you send.
+     *
+     * Separate from `templates` on purpose: saving and rendering run at different
+     * frequencies (autosave would compile MJML on every debounce tick) and fail in
+     * different ways. Every method is optional, and `editor.toMjml()` /
+     * `editor.toHtml()` resolve each one independently:
+     *
+     * | Call | Order |
+     * |---|---|
+     * | `toMjml()` | `render.toMjml` → the bundled `@templatical/renderer` → throw |
+     * | `toHtml()` | `render.toHtml` → `toMjml()`'s result + `render.compileMjml` → throw |
+     *
+     * **Omitted by default**, in which case `toMjml()` renders locally and
+     * `toHtml()` rejects — the SDK deliberately bundles no MJML compiler, so there
+     * is no local HTML path. One endpoint is enough to close that gap:
+     *
+     * ```ts
+     * init({
+     *   container,
+     *   render: {
+     *     compileMjml: (mjml) =>
+     *       fetch("/api/mjml", { method: "POST", body: mjml }).then((r) => r.text()),
+     *   },
+     * });
+     * ```
+     *
+     * Provider methods receive a **render-complete** payload: custom blocks already
+     * resolved to `renderedHtml`, and the editor's effective fonts. Both are things
+     * a backend cannot reconstruct from the template JSON alone.
+     */
+    render?: RenderProvider;
+    /**
+     * Storage backend for the template's **version history** — the past states a
+     * user can browse, preview and restore.
+     *
+     * The editor owns the header's history control, the preview banner and the
+     * restore flow; you own the storage. `list` and `get` are the operations;
+     * `create` and `restore` can each be turned off by passing `false` instead of
+     * a function.
+     *
+     * ```ts
+     * init({
+     *   container,
+     *   versionHistory: {
+     *     list: (templateId) =>
+     *       fetch(`/api/templates/${templateId}/versions`).then((r) => r.json()),
+     *     get: (templateId, versionId) =>
+     *       fetch(`/api/templates/${templateId}/versions/${versionId}`)
+     *         .then((r) => r.json())
+     *         .then((v) => v.content),
+     *     create: false,
+     *     restore: (templateId, versionId) =>
+     *       fetch(`/api/templates/${templateId}/versions/${versionId}/restore`, {
+     *         method: "POST",
+     *       }).then((r) => r.json()),
+     *   },
+     * });
+     * ```
+     *
+     * **Omitted by default** — the control does not render and none of its UI is
+     * downloaded. It also stays hidden until a template is loaded, since a version
+     * belongs to a template id.
+     *
+     * **The editor never records a version by itself.** Whichever
+     * `TemplatesProvider.save` you supply decides whether a save also records one,
+     * so throttling and retention stay with the side that pays for the storage.
+     */
+    versionHistory?: VersionHistoryProvider;
+    /**
+     * Save the template automatically, debounced, after the user stops editing.
+     * Requires a `templates` provider — without one there is nothing to save to,
+     * and the option is ignored with a warning.
+     *
+     * `true` uses the default cadence; `{ debounce }` sets it in the same key. The
+     * debounce governs `onChange` too — both ride one timer so they cannot drift
+     * apart.
+     *
+     * ```ts
+     * autoSave: true                  // default cadence
+     * autoSave: { debounce: 2000 }    // on, slower
+     * ```
+     *
+     * @default false
+     */
+    autoSave?: AutoSaveConfig;
+    /**
+     * Warn the user before they close or reload the tab with unsaved changes.
+     * On by default whenever a `templates` provider is configured — without one
+     * the editor cannot know whether you already persisted the change, so it never
+     * warns.
+     *
+     * Set to `false` to own that prompt yourself. Note it can never cover
+     * client-side route changes; use `onDirtyChange` for those.
+     *
+     * @default true
+     */
+    unsavedChangesGuard?: boolean;
     onRequestMedia?: OnRequestMedia;
     /**
      * Resolves the template for preview surfaces — typically evaluating logic
@@ -614,6 +1006,79 @@ export declare interface TemplaticalEditorConfig {
      * it lives in the user's browser. Validate the recipient on your server.
      */
     testEmail?: TestEmailProvider;
+    /**
+     * Storage backend for **comments** — the review conversation on a template.
+     *
+     * The editor owns the panel, the threading, the resolve flow, the per-block
+     * indicators and the jump-to-block affordance; you own persistence. Five
+     * methods, each mutation turn-off-able by passing `false`:
+     *
+     * ```ts
+     * init({
+     *   container,
+     *   user: { id: "u_7", name: "Ada" },
+     *   comments: {
+     *     list: (templateId) =>
+     *       fetch(`/api/templates/${templateId}/comments`).then((r) => r.json()),
+     *     create: (templateId, input) =>
+     *       fetch(`/api/templates/${templateId}/comments`, {
+     *         method: "POST",
+     *         headers: { "Content-Type": "application/json" },
+     *         body: JSON.stringify(input),
+     *       }).then((r) => r.json()),
+     *     update: (templateId, commentId, patch) =>
+     *       fetch(`/api/templates/${templateId}/comments/${commentId}`, {
+     *         method: "PATCH",
+     *         headers: { "Content-Type": "application/json" },
+     *         body: JSON.stringify(patch),
+     *       }).then((r) => r.json()),
+     *     delete: async (templateId, commentId) => {
+     *       await fetch(`/api/templates/${templateId}/comments/${commentId}`, {
+     *         method: "DELETE",
+     *       });
+     *     },
+     *     setResolved: (templateId, commentId, resolved) =>
+     *       fetch(`/api/templates/${templateId}/comments/${commentId}/resolve`, {
+     *         method: "POST",
+     *         headers: { "Content-Type": "application/json" },
+     *         body: JSON.stringify({ resolved }),
+     *       }).then((r) => r.json()),
+     *   },
+     * });
+     * ```
+     *
+     * **Requires {@link user}** — with no identity the feature reports itself
+     * unavailable and nothing renders, rather than writing anonymous comments.
+     *
+     * **Omitted by default**, and the panel also stays hidden until a template is
+     * loaded, since a comment belongs to a template id.
+     *
+     * Realtime is an optional `subscribe` on the provider, not a prerequisite:
+     * without it comments work identically, you simply see a colleague's on the next
+     * read rather than immediately.
+     */
+    comments?: CommentsProvider;
+    /**
+     * Who is using the editor — needed by any feature that attributes work to a
+     * person. Today that is {@link comments}; collaboration presence will want the
+     * same answer, which is why this is a top-level key rather than part of the
+     * comments provider.
+     *
+     * ```ts
+     * init({ container, user: { id: "u_7", name: "Ada Lovelace" } });
+     * ```
+     *
+     * Not a security boundary — it identifies the user to the editor's UI, in the
+     * user's own browser. Attribute writes server-side from the session your backend
+     * already trusts.
+     */
+    user?: EditorUser;
+    /**
+     * Called for every comment change the editor applied — including ones that
+     * arrived through a provider's `subscribe`, so this is the hook for a "3 new
+     * comments" badge outside the editor.
+     */
+    onComment?: (event: CommentEvent) => void;
     blockDefaults?: BlockDefaults;
     templateDefaults?: TemplateDefaults;
     theme?: ThemeOverrides;
@@ -640,6 +1105,19 @@ export declare interface TemplaticalEditorConfig {
      * @default true
      */
     smallScreenNotice?: boolean;
+    /**
+     * Show the template's name in the header, inline-editable. Defaults to `true`.
+     *
+     * Set to `false` when your store has no name column, or when your own chrome
+     * owns the name. Hides the field only — `create({ name })`, `setName()` and the
+     * `name` in each save patch keep working, so a headless caller or your own UI
+     * can still manage names.
+     *
+     * Without a `templates` provider the header renders no name field either way.
+     *
+     * @default true
+     */
+    templateNameField?: boolean;
     /**
      * Template linter (`@templatical/quality`) configuration. Runs every
      * linter exported by the package (accessibility + structure).
@@ -674,9 +1152,7 @@ export declare interface UseFontsReturn {
     defaultFont: ComputedRef<string>;
     defaultFallback: ComputedRef<string>;
     customFonts: Ref<CustomFont[]>;
-    customFontsEnabled: Ref<boolean>;
     isLoaded: Ref<boolean>;
-    setCustomFontsEnabled: (enabled: boolean) => void;
     loadCustomFonts: () => Promise<void>;
     cleanupFontLinks: () => void;
     getFontWithFallback: (fontName: string) => string;

package/dist/{info-DO5odBcZ.js → info-puX5V6Iq.js}

@@ -1,4 +1,4 @@
-import { t as e } from "./createLucideIcon-C8WzBYCv.js";
+import { t as e } from "./createLucideIcon-L-wQXW_R.js";
 var t = e("info", [
 	["circle", {
 		cx: "12",