@slexkit/tiptap 0.3.3 → 0.5.0

package/README.md

@@ -1,88 +1,45 @@
 # @slexkit/tiptap
 
-Tiptap extension for explicit `slex` fenced UI blocks.
-
-```sh
-npm install slexkit @slexkit/theme-shadcn @slexkit/tiptap @tiptap/core @tiptap/pm @tiptap/starter-kit @tiptap/extension-code-block @tiptap/markdown
-```
-
-Import the SlexKit theme once in your app entry:
+Official Tiptap code-block node view for HTML-first `slex` fences.
 
 ```ts
-import "@slexkit/theme-shadcn/style.css";
-import "@slexkit/tiptap/style.css";
-```
-
-## Minimal setup
-
-```ts
-import { Editor } from "@tiptap/core";
 import StarterKit from "@tiptap/starter-kit";
 import { createSlexKitTiptapExtension } from "@slexkit/tiptap";
+import { createSlexKitMarkdownRuntimeHost } from "slexkit";
 
-const editor = new Editor({
-  element: document.querySelector("#editor"),
-  extensions: [
-    StarterKit.configure({ codeBlock: false }),
-    createSlexKitTiptapExtension({
-      artifactId: "note-42",
-    }),
-  ],
-});
-```
-
-Only code blocks whose language is exactly `slex` are rendered by SlexKit. Other code blocks stay ordinary Tiptap code blocks.
-
-## Markdown roundtrip
-
-Add Tiptap's Markdown extension when loading or exporting Markdown:
-
-```ts
-import { Markdown } from "@tiptap/markdown";
-
-const editor = new Editor({
-  extensions: [
-    StarterKit.configure({ codeBlock: false }),
-    Markdown,
-    createSlexKitTiptapExtension({ artifactId: "doc" }),
-  ],
-  content: markdown,
-  contentType: "markdown",
+const runtimeHost = createSlexKitMarkdownRuntimeHost({
+  secureFrame: { runtimeUrl: "/assets/slexkit.runtime.js" },
 });
 
-const nextMarkdown = editor.getMarkdown();
+const extensions = [
+  StarterKit.configure({ codeBlock: false }),
+  createSlexKitTiptapExtension({ runtimeHost }),
+];
 ```
 
-The adapter uses normal fenced code blocks instead of a custom tokenizer, so ` ```slex ` blocks remain readable in plain Markdown hosts.
-
-## Shared state across fences
-
-All `slex` blocks in one editor share the same artifact runtime by default. A state-only fence can seed later renderable fences:
+The extension replaces only code blocks whose language is exactly `slex`.
+Ordinary code blocks retain normal Tiptap behavior and Markdown round-tripping.
 
 ````md
-```slex
-{
-  namespace: "calc",
-  g: { value: 21 }
-}
-```
-
-```slex
-{
-  namespace: "calc",
-  layout: {
-    "text:answer": { "$text": "'answer: ' + (g.value * 2)" }
-  }
-}
-```
+~~~slex
+<slex-input id="voltage" type="engineering" label="Voltage" value="12"></slex-input>
+<slex-stat id="power" label="Power" unit="W"></slex-stat>
+<script type="module">
+  const voltage = slex.root.querySelector("#voltage");
+  const power = slex.root.querySelector("#power");
+  const update = () => { power.value = voltage.valueAsNumber * 2; };
+  voltage.addEventListener("input", update);
+  update();
+</script>
+~~~
 ````
 
-## Runtime boundary
-
-This adapter defaults to trusted runtime mode, intended for application-authored content, repository-maintained snippets, reviewed examples, and local document workflows. Use SlexKit secure runtime APIs for untrusted user Markdown or direct agent output.
-
-## Documentation
+Each editor owns a stable artifact; each node view owns a stable block ID.
+Updates use the runtime host's preview/commit protocol, so invalid source reports
+a diagnostic without destroying the last committed iframe. The adapter never
+interprets DSL objects, namespaces, state-only blocks, expression strings, or
+handler strings.
 
-- [Official Tiptap editor example](https://slexkit.app.simgor.cn/examples/tiptap-host)
-- [Runnable example source](https://github.com/slexkit/slexkit/tree/main/examples/tiptap)
-- [SlexKit Host integration](https://github.com/slexkit/slexkit/blob/main/site/content/reference/integration/en-US.md)
+Options include `artifactId`, `runtimeHost`, `theme`, `showSource`, labels,
+`className`, and `onError`. Custom legacy hosts remain supported for complete
+commits, though atomic preservation requires `updateArtifact`.

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 import type { Editor } from "@tiptap/core";
-import { type SlexKitMarkdownRuntimeHost, type ThemeMode } from "slexkit";
+import { type SlexKitMarkdownRuntimeHost, type HtmlTheme } from "slexkit";
 export type SlexKitTiptapOptions = {
     artifactId?: string | ((ctx: {
         editor: Editor;
     }) => string);
     runtimeHost?: SlexKitMarkdownRuntimeHost;
-    theme?: ThemeMode;
+    theme?: HtmlTheme;
     showSource?: boolean;
     sourceLabel?: string;
     previewLabel?: string;

package/dist/index.js

@@ -1,5 +1,5 @@
 import CodeBlock from "@tiptap/extension-code-block";
-import { createSlexKitMarkdownRuntimeHost, parseSlexSource, } from "slexkit";
+import { createSlexKitMarkdownRuntimeHost, inspectSlexSource, } from "slexkit";
 const DEFAULT_OPTIONS = {
     showSource: true,
     sourceLabel: "Source",
@@ -20,26 +20,31 @@ const PREVIEW_INTERACTIVE_SELECTOR = [
     "[role='tab']",
     "[role='textbox']",
 ].join(",");
+const TRANSIENT_POINTER_INTERACTIVE_SELECTOR = [
+    "a[href]",
+    "button",
+    "input[type='button']",
+    "input[type='checkbox']",
+    "input[type='image']",
+    "input[type='radio']",
+    "input[type='range']",
+    "input[type='reset']",
+    "input[type='submit']",
+    "[role='button']",
+    "[role='checkbox']",
+    "[role='radio']",
+    "[role='slider']",
+    "[role='switch']",
+    "[role='tab']",
+].join(",");
 const editorArtifactIds = new WeakMap();
 let nextArtifactId = 0;
 const sourceOpenStates = new Map();
 const editorArtifactRuntimes = new WeakMap();
-function isRecord(value) {
-    return !!value && typeof value === "object" && !Array.isArray(value);
-}
-function isRenderableSource(value) {
-    if (!isRecord(value))
-        return false;
-    if ("layout" in value)
-        return isRecord(value.layout) && Object.keys(value.layout).length > 0;
-    if ("namespace" in value || "g" in value)
-        return false;
-    return Object.keys(value).some((key) => key.includes(":"));
-}
-function isStateOnlySource(value) {
-    return isRecord(value)
-        && !isRenderableSource(value)
-        && ("slex" in value || "namespace" in value || "g" in value);
+function isIncrementalRuntimeHost(host) {
+    const candidate = host;
+    return typeof candidate.updateArtifact === "function"
+        && typeof candidate.resetArtifact === "function";
 }
 function resolveArtifactId(editor, option) {
     if (typeof option === "function")
@@ -82,6 +87,8 @@ function resolveArtifactRuntime(editor, artifactId, runtimeHost) {
             runtimeHost: runtimeHost ?? createSlexKitMarkdownRuntimeHost(),
             views: new Set(),
             scheduled: false,
+            pending: Promise.resolve(),
+            nextBlockId: 0,
         };
         runtimes.set(artifactId, runtime);
     }
@@ -93,8 +100,36 @@ function scheduleArtifactRender(runtime) {
     runtime.scheduled = true;
     queueMicrotask(() => {
         runtime.scheduled = false;
-        runtime.runtimeHost.disposeArtifact(runtime.artifactId);
-        for (const view of Array.from(runtime.views).sort(compareNodeViewOrder)) {
+        const views = Array.from(runtime.views).sort(compareNodeViewOrder);
+        if (isIncrementalRuntimeHost(runtime.runtimeHost)) {
+            const prepared = views.map((view) => view.prepareIncrementalRender());
+            const phase = prepared.every((entry) => entry.valid)
+                ? "commit"
+                : "preview";
+            const host = runtime.runtimeHost;
+            const update = async () => {
+                if (runtime.disposed)
+                    return;
+                try {
+                    await host.updateArtifact(runtime.artifactId, prepared.map((entry) => entry.block), { phase });
+                    if (phase === "commit") {
+                        for (const entry of prepared) {
+                            entry.view.finishIncrementalRender();
+                        }
+                    }
+                }
+                catch (error) {
+                    if (phase === "commit") {
+                        for (const entry of prepared) {
+                            entry.view.reportIncrementalError(error);
+                        }
+                    }
+                }
+            };
+            runtime.pending = runtime.pending.then(update, update);
+            return;
+        }
+        for (const view of views) {
             view.renderWithRuntime(runtime.runtimeHost);
         }
     });
@@ -105,6 +140,7 @@ function unregisterArtifactRuntime(editor, runtime, view) {
         scheduleArtifactRender(runtime);
         return;
     }
+    runtime.disposed = true;
     runtime.runtimeHost.disposeArtifact(runtime.artifactId);
     editorArtifactRuntimes.get(editor)?.delete(runtime.artifactId);
 }
@@ -125,8 +161,17 @@ function focusPreviewInteractiveTarget(event) {
     const target = event.target;
     const targetElement = target instanceof Element ? target : target instanceof Node ? target.parentElement : null;
     const interactive = targetElement?.closest(PREVIEW_INTERACTIVE_SELECTOR);
-    if (interactive instanceof HTMLElement)
-        interactive.focus({ preventScroll: true });
+    if (!(interactive instanceof HTMLElement))
+        return null;
+    interactive.focus({ preventScroll: true });
+    return interactive;
+}
+function shouldRestorePreviewFocusAfterPointer(element) {
+    return !!element.closest(TRANSIENT_POINTER_INTERACTIVE_SELECTOR);
+}
+function pointerIdFromEvent(event) {
+    const pointerEvent = event;
+    return typeof pointerEvent?.pointerId === "number" ? pointerEvent.pointerId : undefined;
 }
 function markPreviewInteractive(preview, force = false) {
     if (preview.getAttribute("contenteditable") !== "false") {
@@ -134,18 +179,38 @@ function markPreviewInteractive(preview, force = false) {
     }
     preview.querySelectorAll(PREVIEW_INTERACTIVE_SELECTOR).forEach((element) => {
         if (element instanceof HTMLElement && (force || element.getAttribute("contenteditable") !== "true")) {
-            if (force)
+            if (force && !element.contains(preview.ownerDocument.activeElement))
                 element.removeAttribute("contenteditable");
             element.setAttribute("contenteditable", "true");
         }
     });
 }
+const previewMarks = new WeakMap();
+function cancelPreviewInteractiveMark(preview) {
+    const pending = previewMarks.get(preview);
+    if (!pending)
+        return;
+    pending.cancelled = true;
+    if (pending.timer !== undefined)
+        preview.ownerDocument.defaultView?.clearTimeout(pending.timer);
+    if (pending.frame !== undefined)
+        preview.ownerDocument.defaultView?.cancelAnimationFrame(pending.frame);
+    previewMarks.delete(preview);
+}
 function schedulePreviewInteractiveMark(preview) {
     markPreviewInteractive(preview);
-    queueMicrotask(() => markPreviewInteractive(preview, true));
+    if (previewMarks.has(preview))
+        return;
+    const pending = { cancelled: false };
+    previewMarks.set(preview, pending);
+    const mark = () => { if (!pending.cancelled)
+        markPreviewInteractive(preview, true); };
+    queueMicrotask(mark);
     const win = preview.ownerDocument.defaultView;
-    win?.setTimeout(() => markPreviewInteractive(preview, true), 0);
-    win?.requestAnimationFrame(() => markPreviewInteractive(preview, true));
+    pending.timer = win?.setTimeout(() => { pending.timer = undefined; mark(); if (pending.frame === undefined)
+        previewMarks.delete(preview); }, 0);
+    pending.frame = win?.requestAnimationFrame(() => { pending.frame = undefined; mark(); if (pending.timer === undefined)
+        previewMarks.delete(preview); });
 }
 function renderError(error, source, container) {
     const doc = container.ownerDocument || document;
@@ -192,15 +257,113 @@ class SlexKitCodeBlockNodeView {
     editor;
     options;
     preview;
+    diagnostic;
     runtime;
+    blockId;
     interactiveObserver;
+    pendingFocusRestore;
+    pointerFocusContext;
+    focusTimers = new Set();
+    focusFrames = new Set();
+    clearKeyboardPointerIntent = () => {
+        this.pointerFocusContext = undefined;
+        this.pendingFocusRestore = undefined;
+        this.removeFocusRestoreListeners();
+        this.cancelFocusWork();
+    };
+    cancelFocusWork() {
+        const win = this.preview.ownerDocument.defaultView;
+        for (const timer of this.focusTimers)
+            win?.clearTimeout(timer);
+        for (const frame of this.focusFrames)
+            win?.cancelAnimationFrame(frame);
+        this.focusTimers.clear();
+        this.focusFrames.clear();
+    }
     renderToken = 0;
+    focusPreviewPointerTarget = (event) => {
+        const restoreEditor = this.editor.isFocused;
+        const interactive = focusPreviewInteractiveTarget(event);
+        this.pointerFocusContext = { restoreEditor, expiresAt: Date.now() + 500,
+            scope: interactive?.closest(".slex-select,.slex-checkbox,.slex-switch,.slex-tabs") ?? interactive ?? undefined };
+        if (!interactive || !shouldRestorePreviewFocusAfterPointer(interactive))
+            return;
+        this.pendingFocusRestore = {
+            target: interactive,
+            restoreEditor,
+            pointerId: typeof event.pointerId === "number" ? event.pointerId : null,
+        };
+        this.addFocusRestoreListeners();
+    };
+    clearPointerFocusedPreviewTarget = (event) => {
+        const context = this.pointerFocusContext;
+        if (!context || Date.now() > context.expiresAt)
+            return;
+        const target = event.target;
+        const targetElement = target instanceof Element ? target : target instanceof Node ? target.parentElement : null;
+        const interactive = targetElement?.closest(TRANSIENT_POINTER_INTERACTIVE_SELECTOR);
+        if (!(interactive instanceof HTMLElement))
+            return;
+        if (context.scope && !context.scope.contains(interactive))
+            return;
+        if (this.pendingFocusRestore?.target === interactive)
+            return;
+        this.queuePreviewFocusCleanup({
+            target: interactive,
+            restoreEditor: context.restoreEditor,
+        });
+    };
+    finishPreviewPointerFocus = (event) => {
+        const pending = this.pendingFocusRestore;
+        if (!pending)
+            return;
+        const pointerId = pointerIdFromEvent(event);
+        if (pointerId !== undefined
+            && pending.pointerId !== null
+            && pointerId !== pending.pointerId) {
+            return;
+        }
+        this.pendingFocusRestore = undefined;
+        this.removeFocusRestoreListeners();
+        this.queuePreviewFocusCleanup(pending);
+    };
+    queuePreviewFocusCleanup(pending) {
+        const doc = this.preview.ownerDocument || document;
+        const win = doc.defaultView;
+        const cleanupFocus = () => {
+            if (!this.dom.isConnected)
+                return;
+            const active = doc.activeElement;
+            const clearedTarget = active === pending.target;
+            if (clearedTarget)
+                pending.target.blur();
+            const nextActive = doc.activeElement;
+            const canRestoreEditor = pending.restoreEditor
+                && !this.editor.isDestroyed
+                && (clearedTarget || nextActive === doc.body || nextActive === doc.documentElement);
+            if (canRestoreEditor) {
+                this.editor.commands.focus(undefined, { scrollIntoView: false });
+            }
+        };
+        if (!win)
+            return;
+        for (const ms of [0, 50]) {
+            const timer = win.setTimeout(() => { this.focusTimers.delete(timer); cleanupFocus(); }, ms);
+            this.focusTimers.add(timer);
+        }
+        const frame = win.requestAnimationFrame(() => { this.focusFrames.delete(frame); cleanupFocus(); });
+        this.focusFrames.add(frame);
+    }
+    cancelPreviewPointerFocus = (event) => {
+        this.finishPreviewPointerFocus(event);
+    };
     constructor(node, props, options) {
         this.node = node;
         this.options = options;
         this.editor = props.editor;
         this.artifactId = resolveArtifactId(props.editor, options.artifactId);
         this.runtime = resolveArtifactRuntime(props.editor, this.artifactId, options.runtimeHost);
+        this.blockId = `tiptap-block-${++this.runtime.nextBlockId}`;
         this.runtime.views.add(this);
         const doc = props.view.dom.ownerDocument || document;
         this.dom = createElement(doc, "div", ["slex-tiptap-block", options.className].filter(Boolean).join(" "));
@@ -210,8 +373,11 @@ class SlexKitCodeBlockNodeView {
         if (label)
             label.textContent = options.previewLabel;
         this.preview = createElement(doc, "div", "slex-tiptap-preview");
+        this.diagnostic = createElement(doc, "div", "slex-tiptap-diagnostic");
         this.preview.setAttribute("contenteditable", "false");
-        this.preview.addEventListener("pointerdown", focusPreviewInteractiveTarget, { capture: true });
+        doc.addEventListener("keydown", this.clearKeyboardPointerIntent, { capture: true });
+        this.preview.addEventListener("pointerdown", this.focusPreviewPointerTarget, { capture: true });
+        this.preview.addEventListener("focusin", this.clearPointerFocusedPreviewTarget, { capture: true });
         this.preview.addEventListener("mousedown", focusPreviewInteractiveTarget, { capture: true });
         this.preview.addEventListener("click", focusPreviewInteractiveTarget, { capture: true });
         if (typeof MutationObserver !== "undefined") {
@@ -259,13 +425,13 @@ class SlexKitCodeBlockNodeView {
             sourceToggle.addEventListener("click", stopSourceClick, { capture: true });
             setSourceOpen(sourceOpen);
             sourceShell.append(sourceToggle, pre);
-            this.dom.append(...[label, this.preview, sourceShell].filter((element) => !!element));
+            this.dom.append(...[label, this.diagnostic, this.preview, sourceShell].filter((element) => !!element));
         }
         else {
             const sourceShell = createElement(doc, "div", "slex-tiptap-source slex-tiptap-source-hidden");
             sourceShell.hidden = true;
             sourceShell.append(pre);
-            this.dom.append(...[label, this.preview, sourceShell].filter((element) => !!element));
+            this.dom.append(...[label, this.diagnostic, this.preview, sourceShell].filter((element) => !!element));
         }
         scheduleArtifactRender(this.runtime);
     }
@@ -277,7 +443,16 @@ class SlexKitCodeBlockNodeView {
         return true;
     }
     destroy() {
+        this.renderToken += 1;
+        this.cancelFocusWork();
+        this.preview.ownerDocument.removeEventListener("keydown", this.clearKeyboardPointerIntent, { capture: true });
+        cancelPreviewInteractiveMark(this.preview);
         this.interactiveObserver?.disconnect();
+        this.removeFocusRestoreListeners();
+        this.preview.removeEventListener("pointerdown", this.focusPreviewPointerTarget, { capture: true });
+        this.preview.removeEventListener("mousedown", focusPreviewInteractiveTarget, { capture: true });
+        this.preview.removeEventListener("click", focusPreviewInteractiveTarget, { capture: true });
+        this.preview.removeEventListener("focusin", this.clearPointerFocusedPreviewTarget, { capture: true });
         this.preview.replaceChildren();
         unregisterArtifactRuntime(this.editor, this.runtime, this);
     }
@@ -297,6 +472,8 @@ class SlexKitCodeBlockNodeView {
         const target = mutation.target;
         if (this.preview.contains(target))
             return true;
+        if (this.diagnostic.contains(target))
+            return true;
         if (target === this.contentDOM || this.contentDOM.contains(target))
             return false;
         const targetElement = target instanceof Element ? target : target.parentElement;
@@ -315,41 +492,78 @@ class SlexKitCodeBlockNodeView {
             scheduleArtifactRender(this.runtime);
         });
     }
+    addFocusRestoreListeners() {
+        const doc = this.preview.ownerDocument || document;
+        doc.addEventListener("pointerup", this.finishPreviewPointerFocus, { capture: true });
+        doc.addEventListener("pointercancel", this.cancelPreviewPointerFocus, { capture: true });
+        doc.defaultView?.addEventListener("blur", this.cancelPreviewPointerFocus);
+    }
+    removeFocusRestoreListeners() {
+        const doc = this.preview.ownerDocument || document;
+        doc.removeEventListener("pointerup", this.finishPreviewPointerFocus, { capture: true });
+        doc.removeEventListener("pointercancel", this.cancelPreviewPointerFocus, { capture: true });
+        doc.defaultView?.removeEventListener("blur", this.cancelPreviewPointerFocus);
+    }
     renderWithRuntime(runtimeHost) {
         const source = this.source();
         this.dom.hidden = false;
         this.preview.hidden = false;
-        this.preview.replaceChildren();
-        const parsed = parseSlexSource(source);
-        if (!parsed.ok) {
-            renderError(parsed.error, source, this.preview);
-            this.options.onError?.(parsed.error, source);
+        const inspected = inspectSlexSource(source);
+        if (!inspected.ok) {
+            renderError(inspected.error, source, this.diagnostic);
+            this.options.onError?.(inspected.error, source);
             return;
         }
         try {
+            runtimeHost.disposeBlock(this.preview);
             runtimeHost.mountBlock({
                 artifactId: this.artifactId,
+                blockId: this.blockId,
                 source,
                 container: this.preview,
                 theme: this.options.theme,
             });
+            this.diagnostic.replaceChildren();
             schedulePreviewInteractiveMark(this.preview);
         }
         catch (error) {
-            renderError(error, source, this.preview);
+            renderError(error, source, this.diagnostic);
             this.options.onError?.(error, source);
             return;
         }
-        if (isStateOnlySource(parsed.value) && !this.preview.querySelector(".slexkit-root")) {
-            if (!this.options.showSource) {
-                this.dom.hidden = true;
-                this.preview.hidden = true;
-                return;
-            }
-            const placeholder = createElement(this.preview.ownerDocument || document, "div", "slex-tiptap-state");
-            placeholder.textContent = "State block";
-            this.preview.append(placeholder);
+    }
+    prepareIncrementalRender() {
+        const source = this.source();
+        const inspected = inspectSlexSource(source);
+        if (inspected.ok) {
+            this.diagnostic.replaceChildren();
         }
+        else {
+            renderError(inspected.error, source, this.diagnostic);
+            this.options.onError?.(inspected.error, source);
+        }
+        return {
+            view: this,
+            block: {
+                artifactId: this.artifactId,
+                blockId: this.blockId,
+                source,
+                container: this.preview,
+                theme: this.options.theme,
+            },
+            valid: inspected.ok,
+        };
+    }
+    finishIncrementalRender() {
+        this.dom.hidden = false;
+        this.preview.hidden = false;
+        this.diagnostic.replaceChildren();
+        schedulePreviewInteractiveMark(this.preview);
+    }
+    reportIncrementalError(error) {
+        const source = this.source();
+        renderError(error, source, this.diagnostic);
+        this.options.onError?.(error, source);
     }
 }
 export function createSlexKitTiptapExtension(options = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slexkit/tiptap",
-  "version": "0.3.3",
+  "version": "0.5.0",
   "description": "Tiptap extension for SlexKit fenced UI blocks.",
   "author": "SlexKit contributors",
   "type": "module",
@@ -48,9 +48,12 @@
     "@tiptap/extension-code-block": "^3.0.0",
     "@tiptap/markdown": "^3.0.0",
     "@tiptap/pm": "^3.0.0",
-    "slexkit": "^0.3.3"
+    "slexkit": "^0.5.0"
   },
   "peerDependenciesMeta": {
+    "slexkit": {
+      "optional": true
+    },
     "@tiptap/markdown": {
       "optional": true
     }
@@ -60,7 +63,6 @@
     "@tiptap/extension-code-block": "^3.27.1",
     "@tiptap/markdown": "^3.27.1",
     "@tiptap/pm": "^3.27.1",
-    "@tiptap/starter-kit": "^3.27.1",
-    "slexkit": "file:../.."
+    "@tiptap/starter-kit": "^3.27.1"
   }
 }