@slexkit/tiptap 0.4.0 → 0.5.2

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 the app entry:
-
-```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";
-
-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 nextMarkdown = editor.getMarkdown();
-```
-
-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:
-
-````md
-```slex
-{
-  namespace: "calc",
-  g: { value: 21 }
-}
-```
-
-```slex
-{
-  namespace: "calc",
-  layout: {
-    "text:answer": { "$text": "'answer: ' + (g.value * 2)" }
-  }
-}
-```
-````
-
-## 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
-
-- [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)
+# @slexkit/tiptap
+
+Official Tiptap code-block node view for HTML-first `slex` fences.
+
+```ts
+import StarterKit from "@tiptap/starter-kit";
+import { createSlexKitTiptapExtension } from "@slexkit/tiptap";
+import { createSlexKitMarkdownRuntimeHost } from "slexkit";
+
+const runtimeHost = createSlexKitMarkdownRuntimeHost({
+  secureFrame: { runtimeUrl: "/assets/slexkit.runtime.js" },
+});
+
+const extensions = [
+  StarterKit.configure({ codeBlock: false }),
+  createSlexKitTiptapExtension({ runtimeHost }),
+];
+```
+
+The extension replaces only code blocks whose language is exactly `slex`.
+Ordinary code blocks retain normal Tiptap behavior and Markdown round-tripping.
+
+````md
+~~~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>
+~~~
+````
+
+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.
+
+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",
@@ -41,22 +41,10 @@ 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")
@@ -99,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);
     }
@@ -110,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);
         }
     });
@@ -122,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);
 }
@@ -160,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;
@@ -218,15 +257,35 @@ 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;
-        this.pointerFocusContext = { restoreEditor, expiresAt: Date.now() + 500 };
         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 = {
@@ -245,6 +304,8 @@ class SlexKitCodeBlockNodeView {
         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({
@@ -284,9 +345,14 @@ class SlexKitCodeBlockNodeView {
                 this.editor.commands.focus(undefined, { scrollIntoView: false });
             }
         };
-        win?.setTimeout(cleanupFocus, 0);
-        win?.requestAnimationFrame(cleanupFocus);
-        win?.setTimeout(cleanupFocus, 50);
+        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);
@@ -297,6 +363,7 @@ class SlexKitCodeBlockNodeView {
         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(" "));
@@ -306,7 +373,9 @@ 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");
+        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 });
@@ -356,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);
     }
@@ -374,8 +443,15 @@ 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);
@@ -396,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;
@@ -430,37 +508,62 @@ class SlexKitCodeBlockNodeView {
         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,68 +1,68 @@
-{
-  "name": "@slexkit/tiptap",
-  "version": "0.4.0",
-  "description": "Tiptap extension for SlexKit fenced UI blocks.",
-  "author": "SlexKit contributors",
-  "type": "module",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/slexkit/slexkit.git",
-    "directory": "packages/tiptap"
-  },
-  "homepage": "https://github.com/slexkit/slexkit/tree/main/packages/tiptap#readme",
-  "bugs": {
-    "url": "https://github.com/slexkit/slexkit/issues"
-  },
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./style.css": "./style.css"
-  },
-  "files": [
-    "dist/",
-    "style.css",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "bun run scripts/build.ts"
-  },
-  "keywords": [
-    "slexkit",
-    "tiptap",
-    "prosemirror",
-    "markdown",
-    "editor"
-  ],
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  },
-  "peerDependencies": {
-    "@tiptap/core": "^3.0.0",
-    "@tiptap/extension-code-block": "^3.0.0",
-    "@tiptap/markdown": "^3.0.0",
-    "@tiptap/pm": "^3.0.0",
-    "slexkit": "^0.4.0"
-  },
-  "peerDependenciesMeta": {
-    "slexkit": {
-      "optional": true
-    },
-    "@tiptap/markdown": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@tiptap/core": "^3.27.1",
-    "@tiptap/extension-code-block": "^3.27.1",
-    "@tiptap/markdown": "^3.27.1",
-    "@tiptap/pm": "^3.27.1",
-    "@tiptap/starter-kit": "^3.27.1"
-  }
-}
+{
+  "name": "@slexkit/tiptap",
+  "version": "0.5.2",
+  "description": "Tiptap extension for SlexKit fenced UI blocks.",
+  "author": "SlexKit contributors",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/slexkit/slexkit.git",
+    "directory": "packages/tiptap"
+  },
+  "homepage": "https://github.com/slexkit/slexkit/tree/main/packages/tiptap#readme",
+  "bugs": {
+    "url": "https://github.com/slexkit/slexkit/issues"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./style.css": "./style.css"
+  },
+  "files": [
+    "dist/",
+    "style.css",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun run scripts/build.ts"
+  },
+  "keywords": [
+    "slexkit",
+    "tiptap",
+    "prosemirror",
+    "markdown",
+    "editor"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@tiptap/core": "^3.0.0",
+    "@tiptap/extension-code-block": "^3.0.0",
+    "@tiptap/markdown": "^3.0.0",
+    "@tiptap/pm": "^3.0.0",
+    "slexkit": "^0.5.2"
+  },
+  "peerDependenciesMeta": {
+    "slexkit": {
+      "optional": true
+    },
+    "@tiptap/markdown": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@tiptap/core": "^3.27.1",
+    "@tiptap/extension-code-block": "^3.27.1",
+    "@tiptap/markdown": "^3.27.1",
+    "@tiptap/pm": "^3.27.1",
+    "@tiptap/starter-kit": "^3.27.1"
+  }
+}