typewright 0.2.1

package/dist/react/index.d.cts

@@ -0,0 +1,140 @@
+import * as React from 'react';
+import { E as EditorConfig, a as EditorEvents, h as EditorMode, A as AnticipationOptions, k as MdxTransform, e as ComponentMap, S as SandboxOptions } from '../types-CX1GOx0Y.cjs';
+export { C as CommentReply, c as CommentThread, d as CommentsOptions, D as DocChange, f as DocPosition, g as DocRange, b as DocSelection, i as Extensions, F as FoldingOptions, G as GfmFeatures, K as KeymapOptions, M as MathOptions, j as MdxOptions, l as MermaidOptions, P as PresencePeer, m as SettingsCommand, n as SettingsOptions, o as StreamController, p as StreamOptions, q as SyntaxHighlightOptions, T as ThemeOptions } from '../types-CX1GOx0Y.cjs';
+import { f as Command, B as Block } from '../commands-Z3ndUSza.cjs';
+
+/** Imperative handle exposed via a ref on `<TypewrightEditor>`. */
+interface TypewrightEditorHandle {
+    /** Apply a formatting command to the currently-focused editing surface. */
+    applyCommand: (command: Command) => void;
+    /** Switch the editor mode; also fires `onModeChange`. */
+    setMode: (mode: EditorMode) => void;
+}
+/**
+ * Typewright — drop-in Markdown + MDX editor React component.
+ *
+ * v1 engine (real, tested): the string is the source of truth; rendering goes
+ * through the sanitizing renderer (render.ts escapes text, guards URLs, and
+ * never emits raw HTML/MDX), so the `dangerouslySetInnerHTML` below is safe.
+ *
+ * Modes:
+ *  - `edit`     raw Markdown source (textarea) with standard shortcuts
+ *  - `unified`  live preview; click a block to reveal + edit its Markdown source
+ *  - `preview`  fully rendered
+ *  - `read`     fully rendered, no editing affordances
+ *
+ * Deferred to later phases (SPEC.md): character-level inline marker reveal,
+ * custom virtualization/IME, MDX JSX sandbox execution, Mermaid, in-place table
+ * grid, comments/collaboration. These are represented in the design demo.
+ */
+interface TypewrightEditorProps extends EditorConfig, EditorEvents {
+    /** Controlled Markdown value. */
+    value?: string;
+    /** Uncontrolled initial value. */
+    defaultValue?: string;
+    className?: string;
+    style?: React.CSSProperties;
+}
+declare function useInjectStyles(): void;
+declare const TypewrightEditor: React.ForwardRefExoticComponent<TypewrightEditorProps & React.RefAttributes<TypewrightEditorHandle>>;
+
+/**
+ * Streaming preview — renders an AI/LLM token stream incrementally while
+ * anticipating incomplete formatting (SPEC.md §8). Committed blocks are
+ * reconciled in place (stable, no flicker); new blocks animate in and a block
+ * whose type changes (e.g. skeleton → resolved) re-animates. The HTML comes
+ * from the sanitizing renderer + class-only pending markup, so it is safe.
+ *
+ * Drive it with an updating `text` prop, or hand it a `stream` (async iterable
+ * or ReadableStream of string chunks).
+ */
+interface StreamingPreviewProps {
+    /** Controlled accumulated text. */
+    text?: string;
+    /** A stream of chunks to consume (alternative to `text`). */
+    stream?: AsyncIterable<string> | ReadableStream<string>;
+    /** Which incomplete constructs to optimistically render. */
+    anticipate?: boolean | AnticipationOptions;
+    /**
+     * Reveal characters smoothly rather than in raw chunk jumps (only affects the
+     * `stream` path — the controlled `text` prop is the host's to pace). `true`
+     * uses a default rate; `{ charsPerSecond }` sets it. Mirrors `StreamOptions.smooth`.
+     */
+    smooth?: boolean | {
+        charsPerSecond: number;
+    };
+    /** Label shown inside the skeleton of a component whose props are still streaming. */
+    componentFallback?: string;
+    className?: string;
+    style?: React.CSSProperties;
+}
+declare function StreamingPreview(props: StreamingPreviewProps): React.ReactElement;
+
+/**
+ * SandboxIsland — one executable widget island rendered *as the sandbox iframe*
+ * (Phase D4 / E1, SPEC.md §7/§11). The compiled MDX / Mermaid output stays
+ * **inside** the opaque-origin `<iframe sandbox="allow-scripts">` created by
+ * {@link createSandbox}; the host tree never `innerHTML`s the untrusted output
+ * (invariant K-3). The iframe itself is the widget — this component only mounts
+ * the sandbox into a container `<div>` it owns, un-hides + sizes the iframe once
+ * the sandbox reports a height, and shows an inline error card on failure.
+ *
+ * Lifecycle:
+ *  - **create/reuse** — a single sandbox is created on mount (in a container ref
+ *    passed as {@link createSandbox}'s `container`) and reused across `code`
+ *    edits; it is recreated only when the engine identity changes (a Mermaid
+ *    engine or CSP is baked into the sandbox document at creation).
+ *  - **evaluate** — DEBOUNCED ~250 ms after `code` (or the MDX transform/
+ *    components) change: `mdx` → `resolveTransform(transform)(code)` then
+ *    `sandbox.evaluate(js, {components})`; `mermaid` → `sandbox.renderMermaid(code)`.
+ *  - **destroy** — the sandbox is torn down on unmount.
+ *
+ * Failure handling (invariant K-6 — editing must never break): a transform
+ * throw, an `evaluate`/`renderMermaid` error result, or any unexpected throw is
+ * caught and surfaced as an inline `.tw-island-error` card (the message is
+ * rendered as escaped text by React, never as HTML). The component itself never
+ * throws during render.
+ *
+ * With no MDX transform configured the island falls back to the escaped source
+ * in a `<pre>` (the "no transform" case) — the same safe form the renderer uses.
+ */
+interface SandboxIslandProps {
+    /** `mdx` runs a compiled MDX module; `mermaid` renders a diagram. */
+    kind: 'mdx' | 'mermaid';
+    /** Raw `mdxFlow` source (mdx), or the Mermaid diagram source (mermaid). */
+    code: string;
+    /** How to compile the MDX source to runnable JS (mdx only). */
+    transform?: MdxTransform;
+    /** Components made available to the compiled module (mdx only). */
+    components?: ComponentMap;
+    /** Sandbox options (opaque-origin iframe; `allowSameOrigin` is type-forbidden). */
+    sandbox?: SandboxOptions;
+    /** Resolved Mermaid engine JavaScript *source*, inlined into the sandbox (mermaid only). */
+    mermaidEngine?: string;
+    /** Colour scheme hint applied to the iframe + error card. */
+    theme?: 'light' | 'dark';
+}
+declare function SandboxIslandBase(props: SandboxIslandProps): React.ReactElement;
+/**
+ * Memoized so an island only re-compiles/re-renders when its own `code`/config
+ * changes — a keystroke in a *different* block leaves every island untouched.
+ */
+declare const SandboxIsland: React.MemoExoticComponent<typeof SandboxIslandBase>;
+
+interface CaretRevealBlockProps {
+    /** The parsed block whose offsets index into {@link source}. */
+    block: Block;
+    /** Full document source (the single source of truth). */
+    source: string;
+    /** Emit a scoped splice: `source[from..to]` becomes `insert`. */
+    onChange: (change: {
+        from: number;
+        to: number;
+        insert: string;
+    }) => void;
+    readOnly?: boolean;
+}
+declare function CaretRevealBlock(props: CaretRevealBlockProps): React.ReactElement;
+declare const CARET_REVEAL_CSS = "\n.tw-caret-block{white-space:pre-wrap;overflow-wrap:break-word;outline:none;cursor:text;border-radius:6px;padding:1px 4px;margin-left:-4px;transition:background .15s}\n.tw-mode-unified .tw-caret-block:hover{background:var(--tw-accent-soft)}\n.tw-caret-block:focus-visible{outline:2px solid var(--tw-accent);outline-offset:2px}\n.tw-caret-block.tw-cr-heading{font-weight:680;letter-spacing:-.02em;line-height:1.25}\n.tw-caret-block.tw-cr-h1{font-size:1.8em} .tw-caret-block.tw-cr-h2{font-size:1.45em} .tw-caret-block.tw-cr-h3{font-size:1.2em} .tw-caret-block.tw-cr-h4{font-size:1.05em} .tw-caret-block.tw-cr-h5{font-size:1em} .tw-caret-block.tw-cr-h6{font-size:.92em;color:var(--tw-muted)}\n.tw-caret-block.tw-cr-blockquote{border-left:3px solid var(--tw-line);padding-left:14px;color:var(--tw-muted)}\n.tw-caret-block.tw-cr-list{padding-left:6px}\n.tw-caret-block a{color:var(--tw-accent);text-decoration:none;border-bottom:1px solid var(--tw-accent-soft)}\n.tw-caret-block code{font-family:\"SF Mono\",ui-monospace,Menlo,monospace;font-size:.88em;background:var(--tw-chip);border:1px solid var(--tw-line);border-radius:5px;padding:1px 5px}\n.tw-caret-block .tw-cr-img{color:var(--tw-muted);font-style:italic}\n.tw-caret-block .tw-fnref{font-size:.82em;color:var(--tw-accent)}\n/* Revealed marker: subtle, monospace, \"you are editing raw syntax\". */\n.tw-syntax{font-family:\"SF Mono\",ui-monospace,Menlo,monospace;color:var(--tw-faint);opacity:.85;font-weight:400;font-style:normal}\n/* Hidden marker: collapsed out of layout, but its source chars stay in the DOM\n   (and in this component's offset mapping) \u2014 never removed from the string. */\n.tw-syntax--hidden{display:none}\n@media (prefers-reduced-motion: reduce){ .tw-caret-block{transition:none} }\n";
+
+export { AnticipationOptions, CARET_REVEAL_CSS, CaretRevealBlock, type CaretRevealBlockProps, ComponentMap, EditorConfig, EditorEvents, EditorMode, MdxTransform, SandboxIsland, type SandboxIslandProps, SandboxOptions, StreamingPreview, type StreamingPreviewProps, TypewrightEditor, type TypewrightEditorHandle, type TypewrightEditorProps, useInjectStyles };

package/dist/react/index.d.ts

@@ -0,0 +1,140 @@
+import * as React from 'react';
+import { E as EditorConfig, a as EditorEvents, h as EditorMode, A as AnticipationOptions, k as MdxTransform, e as ComponentMap, S as SandboxOptions } from '../types-CX1GOx0Y.js';
+export { C as CommentReply, c as CommentThread, d as CommentsOptions, D as DocChange, f as DocPosition, g as DocRange, b as DocSelection, i as Extensions, F as FoldingOptions, G as GfmFeatures, K as KeymapOptions, M as MathOptions, j as MdxOptions, l as MermaidOptions, P as PresencePeer, m as SettingsCommand, n as SettingsOptions, o as StreamController, p as StreamOptions, q as SyntaxHighlightOptions, T as ThemeOptions } from '../types-CX1GOx0Y.js';
+import { f as Command, B as Block } from '../commands-Z3ndUSza.js';
+
+/** Imperative handle exposed via a ref on `<TypewrightEditor>`. */
+interface TypewrightEditorHandle {
+    /** Apply a formatting command to the currently-focused editing surface. */
+    applyCommand: (command: Command) => void;
+    /** Switch the editor mode; also fires `onModeChange`. */
+    setMode: (mode: EditorMode) => void;
+}
+/**
+ * Typewright — drop-in Markdown + MDX editor React component.
+ *
+ * v1 engine (real, tested): the string is the source of truth; rendering goes
+ * through the sanitizing renderer (render.ts escapes text, guards URLs, and
+ * never emits raw HTML/MDX), so the `dangerouslySetInnerHTML` below is safe.
+ *
+ * Modes:
+ *  - `edit`     raw Markdown source (textarea) with standard shortcuts
+ *  - `unified`  live preview; click a block to reveal + edit its Markdown source
+ *  - `preview`  fully rendered
+ *  - `read`     fully rendered, no editing affordances
+ *
+ * Deferred to later phases (SPEC.md): character-level inline marker reveal,
+ * custom virtualization/IME, MDX JSX sandbox execution, Mermaid, in-place table
+ * grid, comments/collaboration. These are represented in the design demo.
+ */
+interface TypewrightEditorProps extends EditorConfig, EditorEvents {
+    /** Controlled Markdown value. */
+    value?: string;
+    /** Uncontrolled initial value. */
+    defaultValue?: string;
+    className?: string;
+    style?: React.CSSProperties;
+}
+declare function useInjectStyles(): void;
+declare const TypewrightEditor: React.ForwardRefExoticComponent<TypewrightEditorProps & React.RefAttributes<TypewrightEditorHandle>>;
+
+/**
+ * Streaming preview — renders an AI/LLM token stream incrementally while
+ * anticipating incomplete formatting (SPEC.md §8). Committed blocks are
+ * reconciled in place (stable, no flicker); new blocks animate in and a block
+ * whose type changes (e.g. skeleton → resolved) re-animates. The HTML comes
+ * from the sanitizing renderer + class-only pending markup, so it is safe.
+ *
+ * Drive it with an updating `text` prop, or hand it a `stream` (async iterable
+ * or ReadableStream of string chunks).
+ */
+interface StreamingPreviewProps {
+    /** Controlled accumulated text. */
+    text?: string;
+    /** A stream of chunks to consume (alternative to `text`). */
+    stream?: AsyncIterable<string> | ReadableStream<string>;
+    /** Which incomplete constructs to optimistically render. */
+    anticipate?: boolean | AnticipationOptions;
+    /**
+     * Reveal characters smoothly rather than in raw chunk jumps (only affects the
+     * `stream` path — the controlled `text` prop is the host's to pace). `true`
+     * uses a default rate; `{ charsPerSecond }` sets it. Mirrors `StreamOptions.smooth`.
+     */
+    smooth?: boolean | {
+        charsPerSecond: number;
+    };
+    /** Label shown inside the skeleton of a component whose props are still streaming. */
+    componentFallback?: string;
+    className?: string;
+    style?: React.CSSProperties;
+}
+declare function StreamingPreview(props: StreamingPreviewProps): React.ReactElement;
+
+/**
+ * SandboxIsland — one executable widget island rendered *as the sandbox iframe*
+ * (Phase D4 / E1, SPEC.md §7/§11). The compiled MDX / Mermaid output stays
+ * **inside** the opaque-origin `<iframe sandbox="allow-scripts">` created by
+ * {@link createSandbox}; the host tree never `innerHTML`s the untrusted output
+ * (invariant K-3). The iframe itself is the widget — this component only mounts
+ * the sandbox into a container `<div>` it owns, un-hides + sizes the iframe once
+ * the sandbox reports a height, and shows an inline error card on failure.
+ *
+ * Lifecycle:
+ *  - **create/reuse** — a single sandbox is created on mount (in a container ref
+ *    passed as {@link createSandbox}'s `container`) and reused across `code`
+ *    edits; it is recreated only when the engine identity changes (a Mermaid
+ *    engine or CSP is baked into the sandbox document at creation).
+ *  - **evaluate** — DEBOUNCED ~250 ms after `code` (or the MDX transform/
+ *    components) change: `mdx` → `resolveTransform(transform)(code)` then
+ *    `sandbox.evaluate(js, {components})`; `mermaid` → `sandbox.renderMermaid(code)`.
+ *  - **destroy** — the sandbox is torn down on unmount.
+ *
+ * Failure handling (invariant K-6 — editing must never break): a transform
+ * throw, an `evaluate`/`renderMermaid` error result, or any unexpected throw is
+ * caught and surfaced as an inline `.tw-island-error` card (the message is
+ * rendered as escaped text by React, never as HTML). The component itself never
+ * throws during render.
+ *
+ * With no MDX transform configured the island falls back to the escaped source
+ * in a `<pre>` (the "no transform" case) — the same safe form the renderer uses.
+ */
+interface SandboxIslandProps {
+    /** `mdx` runs a compiled MDX module; `mermaid` renders a diagram. */
+    kind: 'mdx' | 'mermaid';
+    /** Raw `mdxFlow` source (mdx), or the Mermaid diagram source (mermaid). */
+    code: string;
+    /** How to compile the MDX source to runnable JS (mdx only). */
+    transform?: MdxTransform;
+    /** Components made available to the compiled module (mdx only). */
+    components?: ComponentMap;
+    /** Sandbox options (opaque-origin iframe; `allowSameOrigin` is type-forbidden). */
+    sandbox?: SandboxOptions;
+    /** Resolved Mermaid engine JavaScript *source*, inlined into the sandbox (mermaid only). */
+    mermaidEngine?: string;
+    /** Colour scheme hint applied to the iframe + error card. */
+    theme?: 'light' | 'dark';
+}
+declare function SandboxIslandBase(props: SandboxIslandProps): React.ReactElement;
+/**
+ * Memoized so an island only re-compiles/re-renders when its own `code`/config
+ * changes — a keystroke in a *different* block leaves every island untouched.
+ */
+declare const SandboxIsland: React.MemoExoticComponent<typeof SandboxIslandBase>;
+
+interface CaretRevealBlockProps {
+    /** The parsed block whose offsets index into {@link source}. */
+    block: Block;
+    /** Full document source (the single source of truth). */
+    source: string;
+    /** Emit a scoped splice: `source[from..to]` becomes `insert`. */
+    onChange: (change: {
+        from: number;
+        to: number;
+        insert: string;
+    }) => void;
+    readOnly?: boolean;
+}
+declare function CaretRevealBlock(props: CaretRevealBlockProps): React.ReactElement;
+declare const CARET_REVEAL_CSS = "\n.tw-caret-block{white-space:pre-wrap;overflow-wrap:break-word;outline:none;cursor:text;border-radius:6px;padding:1px 4px;margin-left:-4px;transition:background .15s}\n.tw-mode-unified .tw-caret-block:hover{background:var(--tw-accent-soft)}\n.tw-caret-block:focus-visible{outline:2px solid var(--tw-accent);outline-offset:2px}\n.tw-caret-block.tw-cr-heading{font-weight:680;letter-spacing:-.02em;line-height:1.25}\n.tw-caret-block.tw-cr-h1{font-size:1.8em} .tw-caret-block.tw-cr-h2{font-size:1.45em} .tw-caret-block.tw-cr-h3{font-size:1.2em} .tw-caret-block.tw-cr-h4{font-size:1.05em} .tw-caret-block.tw-cr-h5{font-size:1em} .tw-caret-block.tw-cr-h6{font-size:.92em;color:var(--tw-muted)}\n.tw-caret-block.tw-cr-blockquote{border-left:3px solid var(--tw-line);padding-left:14px;color:var(--tw-muted)}\n.tw-caret-block.tw-cr-list{padding-left:6px}\n.tw-caret-block a{color:var(--tw-accent);text-decoration:none;border-bottom:1px solid var(--tw-accent-soft)}\n.tw-caret-block code{font-family:\"SF Mono\",ui-monospace,Menlo,monospace;font-size:.88em;background:var(--tw-chip);border:1px solid var(--tw-line);border-radius:5px;padding:1px 5px}\n.tw-caret-block .tw-cr-img{color:var(--tw-muted);font-style:italic}\n.tw-caret-block .tw-fnref{font-size:.82em;color:var(--tw-accent)}\n/* Revealed marker: subtle, monospace, \"you are editing raw syntax\". */\n.tw-syntax{font-family:\"SF Mono\",ui-monospace,Menlo,monospace;color:var(--tw-faint);opacity:.85;font-weight:400;font-style:normal}\n/* Hidden marker: collapsed out of layout, but its source chars stay in the DOM\n   (and in this component's offset mapping) \u2014 never removed from the string. */\n.tw-syntax--hidden{display:none}\n@media (prefers-reduced-motion: reduce){ .tw-caret-block{transition:none} }\n";
+
+export { AnticipationOptions, CARET_REVEAL_CSS, CaretRevealBlock, type CaretRevealBlockProps, ComponentMap, EditorConfig, EditorEvents, EditorMode, MdxTransform, SandboxIsland, type SandboxIslandProps, SandboxOptions, StreamingPreview, type StreamingPreviewProps, TypewrightEditor, type TypewrightEditorHandle, type TypewrightEditorProps, useInjectStyles };