typewright 0.2.1

package/dist/mdx/index.d.ts

@@ -0,0 +1,252 @@
+import { S as SandboxOptions, k as MdxTransform } from '../types-CX1GOx0Y.js';
+export { e as ComponentMap, M as MathOptions, j as MdxOptions, l as MermaidOptions } from '../types-CX1GOx0Y.js';
+
+/**
+ * `src/sandbox/host.ts` — the opaque-origin execution sandbox (SPEC.md §7, §11).
+ *
+ * Anything executable (compiled MDX, Mermaid diagrams) runs here, never in the
+ * host document. The sandbox is a hidden `<iframe srcdoc sandbox="allow-scripts">`
+ * with an **opaque origin** — `allow-same-origin` is NEVER granted, so a payload
+ * cannot reach `parent.document`, storage, cookies, or the network beyond what
+ * the CSP permits. This closes the XSS→RCE escalation and is Electron-safe.
+ *
+ * Security model (why this is safe without origin checks)
+ * ------------------------------------------------------
+ *  - The iframe is opaque-origin, so every message it posts arrives at the host
+ *    with `event.origin === "null"`. Origin therefore cannot authenticate the
+ *    channel. Instead we validate:
+ *      1. `event.source === iframe.contentWindow` — the message really came from
+ *         *our* frame (not a sibling frame or another window), and
+ *      2. `message.token === <per-instance random token>` — the message carries
+ *         the secret channel token baked into this frame's `srcdoc`.
+ *    Both must hold; mismatches are silently ignored. The same token+source gate
+ *    is applied *inside* the frame (it only accepts messages whose source is its
+ *    `parent` and whose token matches).
+ *  - The CSP baked into the srcdoc is `default-src 'none'` with only
+ *    `'unsafe-inline'` scripts/styles (extendable via {@link SandboxOptions.csp}).
+ *    Compiled modules run as DOM-inserted **inline** `<script>` elements — which
+ *    `'unsafe-inline'` permits — so we never need `'unsafe-eval'`/`new Function`.
+ *  - Compiled output renders **inside** the iframe (the iframe *is* the widget).
+ *    The host never `innerHTML`s compiled output into its own tree. `evaluate`
+ *    resolves with the produced `html` for informational/read-mode use only; the
+ *    host must treat it as untrusted.
+ *  - A component's legitimate host/network needs are brokered: code inside the
+ *    frame calls `host(payload)` → `postMessage({type:'host', payload})` → the
+ *    host's {@link SandboxOptions.onHostMessage}, which proxies the request.
+ *
+ * The message-validation and dispatch logic is factored into pure functions
+ * ({@link shouldAcceptMessage}, {@link dispatchInbound}, {@link buildSandboxCsp},
+ * {@link buildSandboxSrcdoc}) so the protocol is unit-testable without a real
+ * cross-origin frame (end-to-end iframe evaluation is covered by the e2e suite).
+ */
+
+/** Result of evaluating a compiled module inside the sandbox. */
+interface EvaluateResult {
+    /**
+     * Serialized HTML the module produced (already rendered inside the iframe).
+     * Informational only — the host MUST NOT inject this into its own DOM.
+     */
+    html?: string;
+    /** Measured content height of the iframe, for sizing the widget. */
+    height?: number;
+    /** Present when evaluation threw; the module never crashes the host. */
+    error?: string;
+}
+/** Result of rendering a Mermaid diagram inside the sandbox. */
+interface MermaidResult {
+    /** The diagram SVG (already rendered inside the iframe). */
+    svg?: string;
+    height?: number;
+    error?: string;
+}
+/** Controller returned by {@link createSandbox}. */
+interface SandboxController {
+    /**
+     * Evaluate a compiled module body inside the sandbox. `code` is a statement
+     * list that closes over the injected `h`, `components`, `props`, `host`, and
+     * `root`, and returns the rendered result (an HTML string, a DOM node, or
+     * nothing if it mounts into `root` itself). See the transform adapters in
+     * `src/mdx/transform.ts` for the code shape.
+     */
+    evaluate(code: string, props?: Record<string, unknown>): Promise<EvaluateResult>;
+    /** Render a Mermaid diagram source using the injected engine (if any). */
+    renderMermaid(src: string): Promise<MermaidResult>;
+    /** Tear down: remove the iframe, drop listeners, settle pending calls. */
+    destroy(): void;
+}
+/**
+ * Options for {@link createSandbox}. A superset of the public
+ * {@link SandboxOptions} with host-only injection points (an existing
+ * `SandboxOptions` is accepted as-is).
+ */
+interface CreateSandboxOptions extends SandboxOptions {
+    /** Element to append the hidden iframe to (defaults to `document.body`). */
+    container?: HTMLElement;
+    /**
+     * Milliseconds before an `evaluate` / `renderMermaid` call resolves with a
+     * timeout error (never rejects). `0` disables the timeout. Defaults to 8000.
+     */
+    timeoutMs?: number;
+    /**
+     * JavaScript *source* of a Mermaid-compatible engine, inlined into the sandbox
+     * document (see {@link import('../types').MermaidOptions.getEngine}). Expected
+     * to define `self.__twMermaidRender(src)` or `self.mermaid`.
+     */
+    mermaidEngine?: string;
+}
+/** Normalized shape of an inbound result message from the frame. */
+interface InboundResult {
+    html?: string;
+    svg?: string;
+    height?: number;
+    error?: string;
+}
+/**
+ * Decide whether an inbound `message` event should be trusted. Replaces the
+ * origin check (useless for an opaque-origin frame, where `event.origin` is
+ * always `"null"`) with a source-identity + secret-token check.
+ */
+declare function shouldAcceptMessage(event: {
+    source?: unknown;
+    data?: unknown;
+}, ctx: {
+    source: unknown;
+    token: string;
+}): boolean;
+/**
+ * Route a *trusted* inbound message to the right handler. `ready` unlocks the
+ * outbound queue, `host` is brokered to {@link SandboxOptions.onHostMessage},
+ * anything carrying a numeric `id` settles the matching pending call.
+ */
+declare function dispatchInbound(data: Record<string, unknown>, handlers: {
+    onReady?: () => void;
+    onHost?: (payload: unknown) => void;
+    onResult?: (id: number, result: InboundResult) => void;
+}): void;
+/** The strict base CSP for the sandbox document; `extra` is appended. */
+declare function buildSandboxCsp(extra?: string): string;
+/** A per-instance random channel token. Prefers crypto; falls back gracefully. */
+declare function createChannelToken(): string;
+/**
+ * Build the sandbox document. Only trusted, fixed content is inlined here (the
+ * bootstrap and the optional engine source); per-evaluate module code is NEVER
+ * inlined into this string — it is injected at runtime via a script element's
+ * `textContent` (see the bootstrap), which is immune to `</script>` breakout.
+ */
+declare function buildSandboxSrcdoc(params: {
+    token: string;
+    csp: string;
+    engineSource?: string;
+}): string;
+/**
+ * Create a hidden opaque-origin sandbox and return a controller for evaluating
+ * compiled modules and rendering Mermaid inside it. Requires a DOM (browser or
+ * jsdom). Debouncing is the caller's responsibility.
+ */
+declare function createSandbox(opts?: CreateSandboxOptions): SandboxController;
+
+/**
+ * `src/mdx/transform.ts` — MDX transform adapters (SPEC.md §7, step 2).
+ *
+ * Turning JSX/TS into runnable plain JS is the one conceded boundary. This
+ * module resolves an {@link MdxTransform} into a uniform async compile function
+ * `(code, meta?) => Promise<string>`:
+ *
+ *  - `'wasm-esbuild'` → dynamically imports the OPTIONAL peer `esbuild-wasm`.
+ *  - `'wasm-swc'`     → dynamically imports the OPTIONAL peer `@swc/wasm-web`.
+ *      Both peers are never bundled and never hard-imported; if absent, a clear
+ *      Error naming the missing peer is thrown. The host is responsible for
+ *      initializing the wasm engine (its `wasmURL` is environment-specific).
+ *  - `'constrained'`  → a built-in, ZERO-DEPENDENCY transform for a restricted
+ *      MDX-JS subset (see grammar below). No external parser.
+ *  - a function       → returned as-is (host-supplied), wrapped to a Promise.
+ *  - `undefined`      → a transform that throws "no MDX transform configured"
+ *      (the editor treats this as "render escaped source").
+ *
+ * ── Constrained subset (exact, compiled to `h(tag, props, ...children)`) ──────
+ * The constrained transform is a small hand-written recursive-descent parser for
+ * a bounded surface — deliberately NOT a general JS parser. It accepts:
+ *
+ *   Module      := (Line)*                    lines beginning with `import`/`export`
+ *                                             (at column 0) are stripped/hoisted out
+ *   Body        := (Text | Element | Interp)*  the remaining top-level content
+ *   Element     := '<' Name Attr* '/>'
+ *                | '<' Name Attr* '>' Children '</' Name '>'
+ *   Name        := [A-Za-z][A-Za-z0-9._-]*     Capitalized → component; the root
+ *                                             identifier is bound from the map
+ *                                             (`const Chart = components["Chart"]`) and the
+ *                                             tag is emitted bare (`h(Chart, …)`, `h(Foo.Bar, …)`);
+ *                                             lowercase → HTML string tag. A capitalized name
+ *                                             whose segments aren't identifiers is rejected.
+ *   Attr        := Name                        boolean shorthand → `true`
+ *                | Name '=' '"' … '"'          string literal
+ *                | Name '=' "'" … "'"          string literal
+ *                | Name '=' '{' Expr '}'       restricted expression
+ *   Children    := (Text | Element | Interp)*
+ *   Interp      := '{' Expr '}'                interpolation child
+ *   Expr        := number | 'true' | 'false' | 'null'
+ *                | Identifier                  e.g. `name`
+ *                | Identifier ('.' Identifier)+  simple member, e.g. `user.name`
+ *   Text        := run of chars that are not '<' or '{' (JSX entities untouched)
+ *
+ * Anything outside this subset (arrow functions, calls, operators, object/array
+ * literals, template strings, JSX fragments `<>…</>`, spread `{...x}`, mismatched
+ * tags, unterminated constructs) throws a clear Error — it never silently
+ * miscompiles. Hosts needing the full surface use `wasm-esbuild`/`wasm-swc`.
+ *
+ * Output shape: the compiled module is a statement list ending in a `return`,
+ * closing over the sandbox-injected `h`, `components`, and `props`. Example:
+ *   `<Callout type="info">Hi {name}</Callout>`  →
+ *     const Callout = components["Callout"];
+ *     return h(Callout, {"type": "info"}, "Hi ", name);
+ */
+
+interface TransformMeta {
+    filename?: string;
+}
+type CompileFn = (code: string, meta?: TransformMeta) => Promise<string>;
+/** Resolve an {@link MdxTransform} into a uniform async compile function. */
+declare function resolveTransform(t: MdxTransform | undefined): CompileFn;
+/** Compile the restricted MDX subset to a sandbox module string. */
+declare function compileConstrained(source: string): string;
+
+/**
+ * `typewright/mdx` — the sandboxed MDX/Mermaid execution boundary.
+ *
+ * Two pieces, kept separate on purpose (SPEC.md §7):
+ *  - {@link resolveTransform} turns JSX/TS into plain JS (the one conceded
+ *    dependency boundary — wasm peers or a zero-dep constrained subset).
+ *  - {@link createSandbox} runs that plain JS inside an opaque-origin sandboxed
+ *    iframe that cannot reach the host DOM, storage, or session.
+ *
+ * {@link compileAndRun} is the convenience that wires them together for a
+ * one-shot compile-and-render.
+ */
+
+/** Options for {@link compileAndRun}. */
+interface CompileAndRunOptions {
+    /** MDX/JSX source to compile. */
+    code: string;
+    /** How to transform it (defaults to `undefined` → throws "no transform"). */
+    transform?: MdxTransform;
+    /** Transform metadata (e.g. a filename to pick the tsx/jsx loader). */
+    meta?: TransformMeta;
+    /** Props passed to the evaluated module. */
+    props?: Record<string, unknown>;
+    /**
+     * Sandbox options for a freshly-created sandbox. Ignored when `controller`
+     * is supplied.
+     */
+    sandbox?: CreateSandboxOptions;
+    /** Reuse an existing sandbox instead of creating (and destroying) one. */
+    controller?: ReturnType<typeof createSandbox>;
+}
+/**
+ * Compile `code` with the resolved transform and evaluate it in a sandbox. When
+ * no `controller` is supplied a temporary sandbox is created and destroyed
+ * around the call. The compiled output renders inside the sandbox; the returned
+ * `html` is informational — never inject it into the host tree (SPEC.md §11).
+ */
+declare function compileAndRun(opts: CompileAndRunOptions): Promise<EvaluateResult>;
+
+export { type CompileAndRunOptions, type CompileFn, type CreateSandboxOptions, type EvaluateResult, type InboundResult, MdxTransform, type MermaidResult, type SandboxController, SandboxOptions, type TransformMeta, buildSandboxCsp, buildSandboxSrcdoc, compileAndRun, compileConstrained, createChannelToken, createSandbox, dispatchInbound, resolveTransform, shouldAcceptMessage };

package/dist/mdx/index.js

@@ -0,0 +1,3 @@
+export { buildSandboxCsp, buildSandboxSrcdoc, compileAndRun, compileConstrained, createChannelToken, createSandbox, dispatchInbound, resolveTransform, shouldAcceptMessage } from '../chunk-NJ7PJKHN.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/mdx/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}