@draftably/markdown 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,73 @@
-# Temporary Holding Version
+# `@draftably/markdown`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+This package converts canonical `draft` code fences to static SVG image nodes.
+It supports async remark and markdown-it adapters. Static pages do not load or
+compile diagrams in the reader.
+
+Start with the [complete Markdown example](https://github.com/byronwall/draftably/blob/main/docs/integrations/README.md#render-markdown)
+for installation, file storage, and a working first diagram.
+
+The host must provide `emitAsset`. It receives final SVG bytes and returns the
+public URL. Use a durable content-addressed store with your page cache. Re-emit
+the asset on a warm Markdown transform, and retain asset references with cached
+pages. The host owns base paths, publication, cleanup, and watcher integration.
+
+For Node builds, `@draftably/markdown/files` provides a filesystem store for
+content-addressed SVG and interactive JSON assets:
+
+```js
+import { createFileAssets } from '@draftably/markdown/files';
+
+const assets = createFileAssets({ directory: '.cache/diagrams', publicPath: '/docs/diagrams/' });
+const options = { emitAsset: assets.emitAsset };
+// Add `assets.emitInit` to the optional interactive bridge.
+await assets.copyTo('dist/diagrams');
+```
+
+The store checks each filename against the asset bytes and recreates deleted
+files on warm transforms. The host still chooses paths and retains cached page
+references.
+
+Use `src="./diagram.draft"` only with `sources.rootDir` and a Markdown file path.
+The resolver rejects remote and absolute paths, non-`.draft` files, and symlink
+escapes. It reports missing paths as dependencies and the nearest existing
+in-root directory as `watchPath`, so the host can detect when a file appears.
+
+Supported fence keys are `id`, `alt`, `caption`, `src`, `mode`, and `state`.
+Unknown, repeated, malformed, or control-containing values fail the build.
+Captions and alternatives are plain text. The adapter does not evaluate HTML
+or JSX. Inline SVG is not available.
+
+## markdown-it
+
+Call `createMarkdownItDraft(options)` and add its `plugin` to markdown-it. Use
+`adapter.render(md, source, env)` to parse, prepare, and render one document. The
+adapter also exposes `prepare(tokens, env)` for hosts that need custom rendering.
+Prepared state stays local to each token tree, so separate documents can prepare
+at the same time.
+
+## Optional interactive mode
+
+`mode="interactive"` requires a host `interactive` bridge. The bridge emits a
+versioned JSON asset and names the client module. This mode publishes the
+diagram source in that JSON asset by design. Keep the JSON and SVG references
+with the page cache.
+
+The host can load `@draftably/markdown/client` after hydration and call
+`enhanceDrafts(root, { policies })`. The client validates same-origin URLs and
+bounded JSON before it mounts `@draftably/runtime/viewer`. It hides the static
+image only after the viewer commits an update. On failure or destroy, the
+fallback image stays or becomes visible.
+
+The host owns module loading and teardown. Static adapter entry points do not
+import the client or viewer. Use interactive mode only when public source is
+acceptable.
+
+For positioned author errors, preserve mdast positions and inspect
+`file.data.draftably.diagnostics`. Production builds fail by default. Set
+`errors: 'placeholder'` for expected content, metadata, or include errors. Host
+emitter, dependency callback, and renderer failures still fail the build.
+
+See [`docs/integrations/markdown.md`](../../docs/integrations/markdown.md) and
+[`integration-examples/unified/`](../../integration-examples/unified/) for
+pinned Unified, MDX, markdown-it, and interactive consumer proofs.

package/dist/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Byron Wall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/chunks/core-DPjuIyPG.js

@@ -0,0 +1,317 @@
+import { createHash as J } from "node:crypto";
+import { runtimeVersion as W, fontMetricsVersion as Z, renderSvg as H } from "@draftably/runtime";
+import { realpath as D, stat as K, readFile as V } from "node:fs/promises";
+import { resolve as k, relative as q, sep as G, isAbsolute as Y } from "node:path";
+function N(e, t) {
+  const r = q(e, t);
+  return r === "" || r !== ".." && !r.startsWith(`..${G}`) && !Y(r);
+}
+async function Q(e, t, r) {
+  if (!e || e.includes("\0") || e.startsWith("/") || e.startsWith("\\") || /^[A-Za-z][A-Za-z\d+.-]*:/.test(e) || /^[A-Za-z]:/.test(e))
+    throw new Error("src must be a relative local path.");
+  const s = await D(r), g = k(t, "..", e);
+  if (!N(k(r), g))
+    throw new Error("src is outside the configured content root.");
+  let n;
+  try {
+    n = await D(g);
+  } catch (m) {
+    let f = g, y;
+    for (; f !== k(f, ".."); )
+      try {
+        const l = await D(f);
+        if (!N(s, l))
+          throw new Error("src resolves outside the configured content root.", { cause: m });
+        y = l;
+        break;
+      } catch (l) {
+        if (l instanceof Error && l.message.includes("outside"))
+          throw l;
+        f = k(f, "..");
+      }
+    throw Object.assign(new Error("Included .draft file does not exist.", { cause: m }), {
+      missingPath: g,
+      watchPath: y
+    });
+  }
+  if (!N(s, n))
+    throw new Error("src resolves outside the configured content root.");
+  if (!n.endsWith(".draft")) throw new Error("src must name a .draft file.");
+  const p = await K(n);
+  if (!p.isFile()) throw new Error("src must name a regular file.");
+  if (p.size > 1e6) throw new Error("Included .draft file exceeds 1 MB.");
+  const h = await V(n);
+  if (h.byteLength > 1e6) throw new Error("Included .draft file exceeds 1 MB.");
+  return { source: new TextDecoder("utf-8", { fatal: !0 }).decode(h), path: n };
+}
+function z(e, t, r, s) {
+  return {
+    code: e,
+    severity: "error",
+    message: t,
+    location: r,
+    itemIds: [],
+    ...s ? { related: s } : {}
+  };
+}
+function M(e) {
+  return J("sha256").update(e).digest("hex");
+}
+function x(e) {
+  for (const t of e) {
+    const r = t.charCodeAt(0);
+    if (r < 32 || r === 127) return !0;
+  }
+  return !1;
+}
+function c(e, t = "Markdown host operation failed.") {
+  return X(e) ? e : Object.assign(new Error(t, { cause: e }), { hostFailure: !0 });
+}
+function X(e) {
+  return !!e && typeof e == "object" && "hostFailure" in e;
+}
+function P(e, t, r) {
+  return Object.assign(new Error(t), { diagnostic: z(e, t, r) });
+}
+function se(e) {
+  return !!e && typeof e == "object" && "noPlaceholder" in e;
+}
+function F(e) {
+  if (e?.aborted)
+    throw Object.assign(new Error("Markdown diagram preparation was aborted."), {
+      noPlaceholder: !0,
+      cause: e.reason
+    });
+}
+const v = /* @__PURE__ */ new Map(), ee = 128;
+function te(e, t) {
+  const r = e.render ?? {};
+  if (!(r.links?.mode === "safe" && r.links.resolve && !r.links.cacheKey))
+    return JSON.stringify({
+      includeSource: r.includeSource ?? !1,
+      links: r.links ?? { mode: "none" },
+      limits: r.limits ?? {},
+      state: t ?? null,
+      target: "image",
+      fonts: "embed"
+    });
+}
+async function ce(e, t, r, s, g, n) {
+  const p = [];
+  F(n.render?.signal);
+  let h = e, m = s.path, f, y = !1;
+  if (t.src) {
+    if (e.trim())
+      throw P(
+        "DRAFT_INCLUDE",
+        "src cannot be combined with a non-empty fence body.",
+        r
+      );
+    if (!s.path || !n.sources)
+      throw P(
+        "DRAFT_INCLUDE",
+        "src requires a document path and configured sources.rootDir.",
+        r
+      );
+    let i;
+    try {
+      i = await Q(t.src, s.path, n.sources.rootDir);
+    } catch (a) {
+      const { missingPath: u, watchPath: I } = a;
+      if (u)
+        try {
+          n.sources.onDependency?.({
+            documentPath: s.path,
+            dependencyPath: u,
+            missing: !0,
+            watchPath: I
+          });
+        } catch (A) {
+          throw c(A, "Markdown dependency callback failed.");
+        }
+      const o = a instanceof Error ? a.message : "Could not read included diagram.";
+      throw Object.assign(new Error(o), {
+        diagnostic: z(
+          "DRAFT_INCLUDE",
+          o,
+          r,
+          u ? [{ message: "Included here.", location: r }] : void 0
+        )
+      });
+    }
+    h = i.source, m = i.path, y = !0, f = i.path;
+    try {
+      n.sources.onDependency?.({
+        documentPath: s.path,
+        dependencyPath: i.path,
+        missing: !1
+      });
+    } catch (a) {
+      throw c(a, "Markdown dependency callback failed.");
+    }
+  }
+  if (t.mode === "interactive" && !n.interactive) {
+    const i = P(
+      "DRAFT_CAPABILITY",
+      "Interactive diagrams require a configured enhancement bridge.",
+      r
+    );
+    throw Object.assign(i, { noPlaceholder: !0 }), i;
+  }
+  const l = te(n, t.state), b = l === void 0 ? void 0 : M(
+    JSON.stringify([
+      h,
+      m ?? "",
+      W,
+      Z,
+      l
+    ])
+  );
+  let w = b ? v.get(b) : void 0;
+  const L = (i) => i.map((a) => ({
+    ...a,
+    location: a.location ? {
+      ...a.location,
+      line: a.location.line + (y ? 0 : r?.line ?? 1),
+      ...y ? {} : { column: void 0 }
+    } : r,
+    ...y && r ? { related: [...a.related ?? [], { message: "Included here.", location: r }] } : {}
+  }));
+  if (!w) {
+    let i;
+    try {
+      i = await H(h, {
+        ...n.render ?? {},
+        target: "image",
+        fonts: "embed",
+        includeSource: n.render?.includeSource ?? !1,
+        links: n.render?.links ?? { mode: "none" },
+        sourceId: m,
+        state: t.state ?? null
+      });
+    } catch (a) {
+      throw Object.assign(new Error("Draftably renderer failed."), {
+        noPlaceholder: !0,
+        cause: a
+      });
+    }
+    if (!i.ok) {
+      const a = L(i.diagnostics);
+      p.push(...a);
+      const u = Object.assign(new Error("Draftably could not render this diagram."), {
+        diagnostics: a
+      });
+      if ((n.errors ?? "fail") === "fail" || !["input", "limit"].includes(i.reason))
+        throw Object.assign(u, { noPlaceholder: !0 }), u;
+      return {
+        node: { type: "paragraph", children: [{ type: "text", value: "Diagram unavailable." }] },
+        diagnostics: p
+      };
+    }
+    w = {
+      svg: i.value.svg,
+      width: i.value.width,
+      height: i.value.height,
+      title: i.value.title,
+      diagnostics: i.diagnostics
+    }, b && (v.set(b, w), v.size > ee && v.delete(v.keys().next().value));
+  }
+  p.push(...L(w.diagnostics)), F(n.render?.signal);
+  const T = new TextEncoder().encode(w.svg), O = `draft-${M(T)}.svg`;
+  let d;
+  try {
+    d = await n.emitAsset(
+      { fileName: O, mediaType: "image/svg+xml", bytes: T },
+      { document: s, fenceIndex: g }
+    );
+  } catch (i) {
+    throw c(i, "SVG asset emitter failed.");
+  }
+  if (!d || typeof d.url != "string")
+    throw c(new TypeError("Asset emitter must return a URL string."));
+  let R;
+  try {
+    R = new URL(d.url, "https://draftably.invalid");
+  } catch {
+    throw c(new Error("Asset emitter returned an invalid URL."));
+  }
+  if (!d.url || d.url.charCodeAt(0) <= 32 || x(d.url) || !["https:", "http:"].includes(R.protocol))
+    throw c(new Error("Asset emitter returned an unsafe URL."));
+  const U = t.alt?.trim() || w.title, _ = {
+    type: "image",
+    url: d.url,
+    alt: U,
+    data: { hProperties: { width: Math.ceil(w.width), height: Math.ceil(w.height) } }
+  }, B = { fileName: O, url: d.url }, S = [];
+  let j;
+  const E = [_];
+  if (t.mode === "interactive") {
+    const i = n.interactive;
+    if (!/^[A-Za-z0-9._-]{1,64}$/.test(i.policyId))
+      throw c(new TypeError("Interactive policyId must be a short ASCII token."));
+    const a = `draft-${M(JSON.stringify([h, t.state ?? null, t.id ?? null, g])).slice(0, 24)}`, u = {
+      version: 1,
+      key: a,
+      source: h,
+      state: t.state ?? null,
+      label: U,
+      policyId: i.policyId
+    }, I = new TextEncoder().encode(JSON.stringify(u));
+    if (I.byteLength > 1e6)
+      throw P("DRAFT_LIMIT", "Interactive initialization data exceeds 1 MB.", r);
+    let o;
+    try {
+      o = await i.emitInit(u);
+    } catch ($) {
+      throw c($, "Interactive initialization emitter failed.");
+    }
+    if (!o || typeof o.fileName != "string" || typeof o.url != "string")
+      throw c(new TypeError("Initialization emitter must return a filename and URL."));
+    let A, C;
+    try {
+      A = new URL(o.url, "https://draftably.invalid"), C = new URL(i.clientModuleUrl, "https://draftably.invalid");
+    } catch {
+      throw c(new Error("Interactive bridge returned an invalid URL."));
+    }
+    if (o.fileName !== `draft-${M(I)}.json` || !o.url || o.url.charCodeAt(0) <= 32 || x(o.url) || !["https:", "http:"].includes(A.protocol))
+      throw c(new Error("Initialization emitter returned an invalid asset."));
+    if (!i.clientModuleUrl || i.clientModuleUrl.charCodeAt(0) <= 32 || x(i.clientModuleUrl) || !["https:", "http:"].includes(C.protocol))
+      throw c(new Error("clientModuleUrl is unsafe."));
+    S.push({ fileName: o.fileName, url: o.url }), j = i.clientModuleUrl, E.push({
+      type: "div",
+      data: {
+        hName: "div",
+        hProperties: {
+          className: ["draftably-viewer-region"],
+          "data-draftably-region": "",
+          "data-draftably-init": o.url,
+          "data-draftably-policy": i.policyId,
+          "data-draftably-key": a,
+          role: "region",
+          "aria-label": U
+        }
+      },
+      children: []
+    });
+  }
+  return t.caption && E.push({
+    type: "figcaption",
+    data: { hName: "figcaption" },
+    children: [{ type: "text", value: t.caption }]
+  }), { node: t.mode === "interactive" || t.caption ? {
+    type: "figure",
+    data: { hName: "figure", ...t.id ? { hProperties: { id: t.id } } : {} },
+    children: E
+  } : {
+    type: "paragraph",
+    ...t.id ? { data: { hProperties: { id: t.id } } } : {},
+    children: E
+  }, asset: B, extraAssets: S, clientModule: j, diagnostics: p, dependency: f };
+}
+export {
+  se as a,
+  c as h,
+  X as i,
+  z as m,
+  ce as p
+};

package/dist/chunks/metadata-Dx6T_2Zy.js

@@ -0,0 +1,53 @@
+function w(a) {
+  const n = a.charCodeAt(0);
+  return n < 32 || n === 127;
+}
+function f(a) {
+  const n = /^draft(?:\s+\{([\s\S]*)\})?$/.exec(a.trim());
+  if (!n)
+    throw new Error('Expected the canonical draft fence, optionally followed by {key="value"}.');
+  const r = n[1];
+  if (r === void 0) return {};
+  const t = {};
+  let e = 0;
+  const i = () => {
+    for (; /\s/.test(r[e] ?? "") && e < r.length; ) e++;
+  };
+  for (; e < r.length && (i(), e !== r.length); ) {
+    const o = /^[A-Za-z][A-Za-z0-9_-]*/.exec(r.slice(e))?.[0];
+    if (!o) throw new Error(`Invalid metadata near "${r.slice(e)}".`);
+    if (e += o.length, i(), r[e++] !== "=") throw new Error(`Expected '=' after ${o}.`);
+    if (i(), r[e++] !== '"') throw new Error(`${o} must use a quoted value.`);
+    let c = "", d = !1;
+    for (; e < r.length; ) {
+      const s = r[e++];
+      if (s === '"') {
+        d = !0;
+        break;
+      }
+      if (s === "\\") {
+        const l = r[e++];
+        if (l !== '"' && l !== "\\") throw new Error(`Invalid escape in ${o}.`);
+        c += l;
+      } else {
+        if (w(s)) throw new Error(`${o} cannot contain control characters.`);
+        c += s;
+      }
+    }
+    if (!d) throw new Error(`Unclosed value for ${o}.`);
+    if (!["id", "alt", "caption", "src", "mode", "state"].includes(o))
+      throw new Error(`Unknown draft option "${o}".`);
+    if (Object.hasOwn(t, o)) throw new Error(`Duplicate draft option "${o}".`);
+    t[o] = c, i();
+  }
+  if (t.id !== void 0 && !/^[A-Za-z0-9_-]+$/.test(t.id))
+    throw new Error("id must be a non-empty ASCII token.");
+  if (t.mode !== void 0 && t.mode !== "static" && t.mode !== "interactive")
+    throw new Error('mode must be "static" or "interactive".');
+  if (t.src !== void 0 && (!t.src.endsWith(".draft") || t.src.trim() !== t.src || t.src.includes("\0") || t.src.startsWith("/") || t.src.startsWith("\\") || /^[A-Za-z][A-Za-z\d+.-]*:/.test(t.src) || /^[A-Za-z]:/.test(t.src)))
+    throw new Error("src must name a relative local .draft file.");
+  return t;
+}
+export {
+  f as p
+};

package/dist/client.js

@@ -0,0 +1,153 @@
+import { mountViewer as k } from "@draftably/runtime/viewer";
+const m = 1e6, v = 1e6;
+function T(e) {
+  for (const a of e) {
+    const n = a.charCodeAt(0);
+    if (n < 32 || n === 127) return !0;
+  }
+  return !1;
+}
+function p(e, a, n) {
+  if (!e || T(e)) throw new Error("Invalid initialization URL.");
+  const i = new URL(e, n);
+  if (!["http:", "https:"].includes(i.protocol) || i.origin !== a || i.username || i.password)
+    throw new Error("Initialization URL must be same-origin.");
+  return i;
+}
+function A(e, a, n) {
+  if (new TextEncoder().encode(e).byteLength > m) throw new Error("Initialization data exceeds the size limit.");
+  let o;
+  try {
+    o = JSON.parse(e);
+  } catch {
+    throw new Error("Initialization data is not valid JSON.");
+  }
+  if (!o || typeof o != "object" || Array.isArray(o))
+    throw new Error("Initialization data has an invalid shape.");
+  const t = o;
+  if (Object.keys(t).sort().join(",") !== "key,label,policyId,source,state,version")
+    throw new Error("Initialization data has unknown or missing fields.");
+  if (t.version !== 1 || t.key !== a || !/^draft-[0-9a-f]{24}$/.test(a))
+    throw new Error("Initialization identity is invalid.");
+  if (t.policyId !== n || typeof t.policyId != "string")
+    throw new Error("Initialization policy does not match.");
+  if (typeof t.source != "string" || new TextEncoder().encode(t.source).byteLength > v)
+    throw new Error("Diagram source is invalid or too large.");
+  if (typeof t.label != "string" || t.label.length > 2e3)
+    throw new Error("Diagram label is invalid.");
+  if (t.state !== null && typeof t.state != "string")
+    throw new Error("Diagram state is invalid.");
+  return t;
+}
+const u = /* @__PURE__ */ new WeakSet();
+async function S(e) {
+  if (!e.ok) throw new Error(`Initialization request failed with HTTP ${e.status}.`);
+  const a = Number(e.headers.get("content-length"));
+  if (Number.isFinite(a) && a > m)
+    throw new Error("Initialization response exceeds the size limit.");
+  if (!e.body) throw new Error("Initialization response has no body.");
+  const n = e.body.getReader(), i = [];
+  let o = 0;
+  try {
+    for (; ; ) {
+      const { done: s, value: f } = await n.read();
+      if (s) break;
+      if (o += f.byteLength, o > m)
+        throw await n.cancel(), new Error("Initialization response exceeds the size limit.");
+      i.push(f);
+    }
+  } finally {
+    n.releaseLock();
+  }
+  const t = new Uint8Array(o);
+  let l = 0;
+  for (const s of i)
+    t.set(s, l), l += s.byteLength;
+  return new TextDecoder("utf-8", { fatal: !0 }).decode(t);
+}
+function D(e) {
+  return { code: "DRAFT_ENHANCE", severity: "warning", message: e, itemIds: [] };
+}
+function U(e, a) {
+  if (u.has(e))
+    throw new Error("This Markdown root already has an active Draftably enhancement.");
+  u.add(e);
+  const n = e.ownerDocument, i = n.defaultView;
+  if (!i)
+    throw u.delete(e), new Error("The Markdown root has no browser window.");
+  let o = !1;
+  const t = /* @__PURE__ */ new Set(), l = /* @__PURE__ */ new Set(), s = [], f = (r) => {
+    try {
+      a.onDiagnostic?.(D(r));
+    } catch {
+    }
+  }, I = Array.from(
+    e.querySelectorAll("[data-draftably-region][data-draftably-init]")
+  );
+  for (const r of I) {
+    const w = r.closest("figure")?.querySelector("img");
+    if (w) {
+      const h = w.hidden;
+      s.push(() => {
+        w.hidden = h;
+      });
+    }
+    const c = new i.AbortController();
+    t.add(c), (async () => {
+      let h;
+      try {
+        const y = p(
+          r.dataset.draftablyInit ?? "",
+          i.location.origin,
+          n.baseURI
+        ), g = await i.fetch(y, {
+          signal: c.signal,
+          credentials: "same-origin",
+          redirect: "error"
+        });
+        g.url && p(g.url, i.location.origin, n.baseURI);
+        const z = await S(g);
+        if (o || c.signal.aborted) return;
+        const d = A(
+          z,
+          r.dataset.draftablyKey ?? "",
+          r.dataset.draftablyPolicy ?? ""
+        ), b = a.policies.get(d.policyId);
+        if (!b) throw new Error("No viewer policy is configured for this diagram.");
+        if (r.dataset.draftablyKey !== d.key || r.dataset.draftablyPolicy !== d.policyId)
+          throw new Error("Figure markers do not match initialization data.");
+        if (r.childNodes.length) throw new Error("Viewer region is not empty.");
+        h = k(r, { ...b, label: b.label ?? d.label }), l.add(h);
+        const E = await h.update(d.source, {
+          state: d.state,
+          camera: "fit",
+          signal: c.signal
+        });
+        if (o || c.signal.aborted) return;
+        E.status === "committed" && w ? w.hidden = !0 : E.status === "error" && f("The interactive diagram could not load. The static image is still available.");
+      } catch (y) {
+        !o && !c.signal.aborted && f(
+          y instanceof Error ? y.message : "The interactive diagram could not load."
+        );
+      } finally {
+        t.delete(c);
+      }
+    })();
+  }
+  return {
+    destroy() {
+      if (!o) {
+        o = !0;
+        for (const r of t) r.abort();
+        t.clear();
+        for (const r of l) r.destroy();
+        l.clear();
+        for (const r of s) r();
+        s.length = 0, u.delete(e);
+      }
+    }
+  };
+}
+export {
+  U as enhanceDrafts
+};

package/dist/files.js

@@ -0,0 +1,103 @@
+import { randomUUID as v, createHash as $ } from "node:crypto";
+import { mkdir as m, readdir as x, readFile as p, writeFile as b, link as N, rm as U } from "node:fs/promises";
+import { resolve as h, join as l } from "node:path";
+function A(t) {
+  return $("sha256").update(t).digest("hex");
+}
+function g(t, r) {
+  return `draft-${A(t)}.${r}`;
+}
+function j(t) {
+  for (const r of t) {
+    const o = r.charCodeAt(0);
+    if (o < 32 || o === 127) return !0;
+  }
+  return !1;
+}
+function S(t) {
+  if (typeof t != "string" || !t || /[\s\\?#]/.test(t) || j(t))
+    throw new TypeError(
+      "publicPath must be a URL path without query, hash, backslash, or controls."
+    );
+  let r;
+  if (t.startsWith("/")) {
+    if (t.startsWith("//"))
+      throw new TypeError("publicPath must not be protocol-relative.");
+    r = t;
+  } else {
+    let o;
+    try {
+      o = new URL(t);
+    } catch {
+      throw new TypeError("publicPath must be root-relative or an absolute HTTP(S) URL.");
+    }
+    if (!["http:", "https:"].includes(o.protocol) || o.username || o.password)
+      throw new TypeError("publicPath must be root-relative or an absolute HTTP(S) URL.");
+    r = `${o.origin}${o.pathname}`;
+  }
+  return r.replace(/\/+$/, "");
+}
+async function d(t, r, o) {
+  await m(t, { recursive: !0 });
+  const s = l(t, r), c = l(t, `.${r}.${v()}.tmp`);
+  try {
+    await b(c, o, { flag: "wx" });
+    try {
+      await N(c, s);
+    } catch (f) {
+      if (f.code !== "EEXIST") throw f;
+      if (!(await p(s)).equals(o)) throw new Error(`Asset collision: ${r}`, { cause: f });
+    }
+  } finally {
+    await U(c, { force: !0 });
+  }
+}
+function y(t, r) {
+  const o = t.endsWith(".svg") ? "svg" : t.endsWith(".json") ? "json" : void 0;
+  return !!o && t === g(r, o);
+}
+function R(t) {
+  if (!t || typeof t.directory != "string" || !t.directory)
+    throw new TypeError("directory must be a non-empty path.");
+  const r = h(t.directory), o = S(t.publicPath), s = /* @__PURE__ */ new Map();
+  async function c(e, i) {
+    if (!y(e, i))
+      throw new TypeError(`Invalid content-addressed asset name: ${e}`);
+    let n = s.get(e);
+    n || (n = d(r, e, i), s.set(e, n));
+    try {
+      await n;
+    } finally {
+      s.get(e) === n && s.delete(e);
+    }
+  }
+  const f = (e) => `${o}/${e}`, u = async (e) => {
+    if (e.mediaType !== "image/svg+xml" || !e.fileName.endsWith(".svg"))
+      throw new TypeError("Expected a content-addressed Draftably SVG.");
+    return await c(e.fileName, e.bytes), { url: f(e.fileName) };
+  }, T = async (e) => {
+    const i = new TextEncoder().encode(JSON.stringify(e)), n = g(i, "json");
+    return await c(n, i), { fileName: n, url: f(n) };
+  };
+  async function E(e) {
+    const i = h(e);
+    await m(i, { recursive: !0 });
+    let n;
+    try {
+      n = await x(r);
+    } catch (a) {
+      if (a.code === "ENOENT") return;
+      throw a;
+    }
+    for (const a of n) {
+      if (!/^draft-[0-9a-f]{64}\.(?:svg|json)$/.test(a)) continue;
+      const w = await p(l(r, a));
+      if (!y(a, w)) throw new Error(`Asset content hash mismatch: ${a}`);
+      await d(i, a, w);
+    }
+  }
+  return { directory: r, emitAsset: u, emitInit: T, copyTo: E };
+}
+export {
+  R as createFileAssets
+};

package/dist/index.js

@@ -0,0 +1,8 @@
+import "node:crypto";
+import "@draftably/runtime";
+import "node:fs/promises";
+import "node:path";
+import { p as e } from "./chunks/metadata-Dx6T_2Zy.js";
+export {
+  e as parseFenceOptions
+};

package/dist/markdown-it.js

@@ -0,0 +1,155 @@
+import { m as T, p as S, i as P, a as I, h as F } from "./chunks/core-DPjuIyPG.js";
+import { p as j } from "./chunks/metadata-Dx6T_2Zy.js";
+function x(t) {
+  return /^draft(?:\s|$)/.test(t.trim());
+}
+function E(t) {
+  return t.replace(
+    /[&<>"']/g,
+    (r) => ({
+      "&": "&amp;",
+      "<": "&lt;",
+      ">": "&gt;",
+      '"': "&quot;",
+      "'": "&#39;"
+    })[r]
+  );
+}
+function H(t) {
+  const r = `${t.width === void 0 ? "" : ` width="${t.width}"`}${t.height === void 0 ? "" : ` height="${t.height}"`}`;
+  return `<img src="${E(t.url)}" alt="${E(t.alt)}"${r}>`;
+}
+function A(t, r) {
+  const d = t.type;
+  if (d === "paragraph") {
+    const e = t.data?.hProperties ?? {}, l = typeof e.id == "string" ? ` id="${r(e.id)}"` : "", a = t.children.map((o) => A(o, r)).join("");
+    return `<p${l}>${a}</p>
+`;
+  }
+  if (d === "figure") {
+    const l = t.data?.hProperties?.id, h = typeof l == "string" ? ` id="${r(l)}"` : "", a = t.children;
+    return `<figure${h}>${a.map((o) => A(o, r)).join("")}</figure>
+`;
+  }
+  if (d === "image") {
+    const e = t.data?.hProperties ?? {};
+    return H({
+      url: String(t.url ?? ""),
+      alt: String(t.alt ?? ""),
+      ...typeof e.width == "number" ? { width: e.width } : {},
+      ...typeof e.height == "number" ? { height: e.height } : {}
+    });
+  }
+  if (d === "figcaption")
+    return `<figcaption>${t.children.map((l) => A(l, r)).join("")}</figcaption>`;
+  if (d === "div") {
+    const e = t.data?.hProperties ?? {};
+    if (!(e["data-draftably-region"] === "") || typeof e["data-draftably-init"] != "string" || typeof e["data-draftably-policy"] != "string" || typeof e["data-draftably-key"] != "string")
+      throw new Error("Invalid generated viewer region.");
+    const h = typeof e["aria-label"] == "string" ? e["aria-label"] : "Diagram viewer";
+    return `<div class="draftably-viewer-region" data-draftably-region="" data-draftably-init="${r(String(e["data-draftably-init"]))}" data-draftably-policy="${r(String(e["data-draftably-policy"]))}" data-draftably-key="${r(String(e["data-draftably-key"]))}" role="region" aria-label="${r(h)}"></div>`;
+  }
+  if (d === "text") return r(String(t.value ?? ""));
+  throw new Error(`Unsupported generated AST node: ${String(d)}.`);
+}
+function _(t) {
+  if (!t || typeof t.emitAsset != "function")
+    throw new TypeError("createMarkdownItDraft requires an emitAsset function.");
+  const r = /* @__PURE__ */ new WeakMap(), d = (a) => a.type === "fence" && x(a.info ?? "");
+  function e(a) {
+    const o = a, p = o.renderer.rules.fence;
+    o.renderer.rules.fence = function(c, u, g, y, b) {
+      const $ = c[u];
+      if (!d($))
+        return p ? p(c, u, g, y, b) : b.renderToken(c, u, g);
+      const D = r.get($);
+      if (!D)
+        throw new Error(
+          "Draft fence rendered before prepare(). Prepare and render the same token tree."
+        );
+      return A(D.node, (k) => o.utils.escapeHtml(k));
+    };
+  }
+  async function l(a, o, p = {}) {
+    const c = a.parse(o, p), u = await h(c, p);
+    return { html: a.renderer.render(c, a.options, p), manifest: u };
+  }
+  async function h(a, o = {}) {
+    const p = { path: o.draftably?.documentPath }, c = [], u = /* @__PURE__ */ new Set(), g = /* @__PURE__ */ new Set(), y = [], b = /* @__PURE__ */ new Set(), $ = t.sources && {
+      ...t.sources,
+      onDependency: (w) => {
+        u.add(w.dependencyPath);
+        try {
+          t.sources?.onDependency?.(w);
+        } catch (s) {
+          throw F(s, "Markdown dependency callback failed.");
+        }
+      }
+    };
+    let D = 0;
+    const k = async (w) => {
+      for (const s of w) {
+        if (d(s)) {
+          const M = D++, v = { sourceId: p.path, line: (s.map?.[0] ?? 0) + 1 };
+          r.delete(s);
+          try {
+            let n;
+            try {
+              n = j(s.info ?? "");
+            } catch (f) {
+              const m = f instanceof Error ? f.message : "Invalid draft fence metadata.";
+              throw Object.assign(new Error(m), {
+                diagnostic: T("DRAFT_METADATA", m, v)
+              });
+            }
+            if (n.id && b.has(n.id)) {
+              const f = `Duplicate draft id "${n.id}" in this document.`;
+              throw Object.assign(new Error(f), {
+                diagnostic: T("DRAFT_METADATA", f, v)
+              });
+            }
+            n.id && b.add(n.id);
+            const i = await S(s.content ?? "", n, v, p, M, {
+              ...t,
+              sources: $
+            });
+            r.set(s, { node: i.node, diagnostics: i.diagnostics }), i.asset && c.push(i.asset), c.push(...i.extraAssets ?? []), i.dependency && u.add(i.dependency), i.clientModule && g.add(i.clientModule), y.push(...i.diagnostics);
+          } catch (n) {
+            if (P(n)) throw n.cause ?? n;
+            if (I(n)) throw n;
+            const i = n.diagnostic, f = n.diagnostics, m = i ?? f?.[0] ?? T(
+              "DRAFT_BUILD",
+              n instanceof Error ? n.message : "Could not prepare diagram.",
+              v
+            );
+            if (y.push(...f ?? [m]), (t.errors ?? "fail") === "fail")
+              throw Object.assign(new Error("Draftably Markdown preparation failed."), {
+                diagnostics: f ?? [m]
+              });
+            r.set(s, {
+              node: {
+                type: "paragraph",
+                children: [{ type: "text", value: "Diagram unavailable." }]
+              },
+              diagnostics: f ?? [m]
+            });
+          }
+        }
+        s.children?.length && await k(s.children);
+      }
+    };
+    await k(a);
+    for (const w of y) t.onDiagnostic?.(w);
+    return {
+      version: 1,
+      assets: c,
+      clientModules: [...g],
+      dependencies: [...u],
+      diagnostics: y
+    };
+  }
+  return { plugin: e, prepare: h, render: l };
+}
+export {
+  _ as createMarkdownItDraft
+};

package/dist/remark.js

@@ -0,0 +1,86 @@
+import { m as h, p as b, i as k, a as v, h as F } from "./chunks/core-DPjuIyPG.js";
+import { p as x } from "./chunks/metadata-Dx6T_2Zy.js";
+function j(s) {
+  if (!s || typeof s.emitAsset != "function")
+    throw new TypeError("remarkDraft requires an emitAsset function.");
+  return async (D, d) => {
+    const A = { path: d.path }, u = [], m = /* @__PURE__ */ new Set(), p = /* @__PURE__ */ new Set(), E = s.sources && {
+      ...s.sources,
+      onDependency: (i) => {
+        p.add(i.dependencyPath);
+        try {
+          s.sources?.onDependency?.(i);
+        } catch (r) {
+          throw F(r, "Markdown dependency callback failed.");
+        }
+      }
+    }, l = [], g = /* @__PURE__ */ new Set();
+    let M = 0;
+    async function w(i) {
+      const r = i.children;
+      if (r)
+        for (let o = 0; o < r.length; o++) {
+          const n = r[o];
+          if (n.type === "code" && n.lang === "draft") {
+            const T = M++, f = {
+              sourceId: d.path,
+              line: n.position?.start?.line ?? 1,
+              column: n.position?.start?.column
+            };
+            try {
+              let e;
+              try {
+                e = x(n.meta ? `draft ${n.meta}` : "draft");
+              } catch (a) {
+                const c = a instanceof Error ? a.message : "Invalid draft fence metadata.";
+                throw Object.assign(new Error(c), {
+                  diagnostic: h("DRAFT_METADATA", c, f)
+                });
+              }
+              if (e.id && g.has(e.id)) {
+                const a = `Duplicate draft id "${e.id}" in this document.`;
+                throw Object.assign(new Error(a), {
+                  diagnostic: h("DRAFT_METADATA", a, f)
+                });
+              }
+              e.id && g.add(e.id);
+              const t = await b(n.value ?? "", e, f, A, T, {
+                ...s,
+                sources: E
+              });
+              r.splice(o, 1, t.node), t.asset && u.push(t.asset), u.push(...t.extraAssets ?? []), t.clientModule && m.add(t.clientModule), t.dependency && p.add(t.dependency), l.push(...t.diagnostics);
+            } catch (e) {
+              if (k(e)) throw e.cause ?? e;
+              if (v(e)) throw e;
+              const t = e.diagnostic, a = e.diagnostics, c = t ?? a?.[0] ?? h(
+                "DRAFT_BUILD",
+                e instanceof Error ? e.message : "Could not prepare diagram.",
+                f
+              );
+              if (l.push(...a ?? [c]), (s.errors ?? "fail") === "fail") {
+                const y = new Error("Draftably Markdown transform failed.");
+                throw Object.assign(y, { diagnostics: a ?? [c] }), y;
+              }
+              r.splice(o, 1, {
+                type: "paragraph",
+                children: [{ type: "text", value: "Diagram unavailable." }]
+              });
+            }
+          } else
+            await w(n);
+        }
+    }
+    await w(D);
+    for (const i of l) s.onDiagnostic?.(i);
+    d.data ??= {}, d.data.draftably = {
+      version: 1,
+      assets: u,
+      clientModules: [...m],
+      dependencies: [...p],
+      diagnostics: l
+    };
+  };
+}
+export {
+  j as default
+};

package/dist/types/client-validation.d.ts

@@ -0,0 +1,5 @@
+import type { DraftViewerInitV1 } from './core.js';
+export declare const MAX_INIT_BYTES = 1000000;
+export declare const MAX_SOURCE_BYTES = 1000000;
+export declare function sameOriginInitUrl(value: string, origin: string, baseUrl: string): URL;
+export declare function parseInitJson(text: string, expectedKey: string, expectedPolicy: string): DraftViewerInitV1;

package/dist/types/client.d.ts

@@ -0,0 +1,12 @@
+import { mountViewer } from '@draftably/runtime/viewer';
+import type { Diagnostic } from '@draftably/runtime';
+type ViewerOptions = Parameters<typeof mountViewer>[1];
+export interface EnhanceDraftsOptions {
+    policies: ReadonlyMap<string, ViewerOptions>;
+    onDiagnostic?: (diagnostic: Diagnostic) => void;
+}
+/** Load generated init assets and progressively enhance static diagram figures under root. */
+export declare function enhanceDrafts(root: HTMLElement, options: EnhanceDraftsOptions): {
+    destroy(): void;
+};
+export {};

package/dist/types/core.d.ts

@@ -0,0 +1,99 @@
+import type { Diagnostic } from '@draftably/runtime';
+import type { FenceOptions } from './metadata.js';
+export { resolveSource } from './source.js';
+export { parseFenceOptions } from './metadata.js';
+export type { Diagnostic } from '@draftably/runtime';
+export interface DraftDocument {
+    path?: string;
+}
+export interface DraftAsset {
+    fileName: string;
+    mediaType: 'image/svg+xml';
+    bytes: Uint8Array;
+}
+export interface AssetReference {
+    fileName: string;
+    url: string;
+}
+export interface DraftDocumentResult {
+    version: 1;
+    assets: readonly AssetReference[];
+    clientModules: readonly string[];
+    dependencies: readonly string[];
+    diagnostics: readonly Diagnostic[];
+}
+export interface SourceDependency {
+    documentPath: string;
+    dependencyPath: string;
+    missing: boolean;
+    watchPath?: string;
+}
+export type EmitAsset = (asset: DraftAsset, context: {
+    document: DraftDocument;
+    fenceIndex: number;
+}) => Promise<{
+    url: string;
+}>;
+export interface DraftMarkdownOptions {
+    emitAsset: EmitAsset;
+    errors?: 'fail' | 'placeholder';
+    interactive?: MarkdownInteractiveBridge;
+    render?: {
+        includeSource?: boolean;
+        links?: {
+            mode: 'none';
+        } | {
+            mode: 'safe';
+            baseUrl?: string;
+            target?: '_self' | '_blank';
+            cacheKey?: string;
+            resolve?: (request: {
+                itemId: string;
+                href: string;
+            }) => string | null;
+        };
+        limits?: {
+            maxSourceChars?: number;
+            maxSourceBytes?: number;
+            maxOutputBytes?: number;
+            maxObjects?: number;
+            maxEdges?: number;
+            maxDepth?: number;
+        };
+        signal?: AbortSignal;
+    };
+    sources?: {
+        rootDir: string;
+        onDependency?: (dependency: SourceDependency) => void;
+    };
+    onDiagnostic?: (diagnostic: Diagnostic) => void;
+}
+export interface DraftViewerInitV1 {
+    version: 1;
+    key: string;
+    source: string;
+    state: string | null;
+    label: string;
+    policyId: string;
+}
+export interface MarkdownInteractiveBridge {
+    clientModuleUrl: string;
+    policyId: string;
+    emitInit(data: DraftViewerInitV1): Promise<{
+        fileName: string;
+        url: string;
+    }>;
+}
+export declare function makeDiagnostic(code: string, message: string, location?: Diagnostic['location'], related?: Diagnostic['related']): Diagnostic;
+export declare function contentHash(value: string | Uint8Array): string;
+export declare function hostFailure(error: unknown, message?: string): Error;
+export declare function isHostFailure(error: unknown): boolean;
+export declare function isNoPlaceholder(error: unknown): boolean;
+export declare function prepare(source: string, metadata: FenceOptions, location: Diagnostic['location'], document: DraftDocument, fenceIndex: number, options: DraftMarkdownOptions): Promise<{
+    node: Record<string, unknown>;
+    asset?: AssetReference;
+    diagnostics: Diagnostic[];
+    dependency?: string;
+    extraAssets?: AssetReference[];
+    clientModule?: string;
+}>;

package/dist/types/files.d.ts

@@ -0,0 +1,12 @@
+import type { EmitAsset, MarkdownInteractiveBridge } from './core.js';
+export interface FileAssets {
+    directory: string;
+    emitAsset: EmitAsset;
+    emitInit: MarkdownInteractiveBridge['emitInit'];
+    copyTo(directory: string): Promise<void>;
+}
+/** Create a content-addressed Node file store for generated SVG and viewer JSON assets. */
+export declare function createFileAssets(options: {
+    directory: string;
+    publicPath: string;
+}): FileAssets;

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export { parseFenceOptions } from './core.js';
+export type { FenceOptions } from './metadata.js';
+export type { AssetReference, Diagnostic, DraftAsset, DraftDocument, DraftDocumentResult, DraftMarkdownOptions, DraftViewerInitV1, EmitAsset, MarkdownInteractiveBridge, SourceDependency, } from './core.js';

package/dist/types/markdown-it-helpers.d.ts

@@ -0,0 +1,9 @@
+export declare function isDraftFenceInfo(info: string): boolean;
+export interface HtmlImage {
+    url: string;
+    alt: string;
+    width?: number;
+    height?: number;
+}
+export declare function escapeHtml(value: string): string;
+export declare function imageHtml(image: HtmlImage): string;

package/dist/types/markdown-it.d.ts

@@ -0,0 +1,30 @@
+import { type DraftDocumentResult, type DraftMarkdownOptions } from './core.js';
+export interface DraftMarkdownItEnvironment {
+    draftably?: {
+        documentPath?: string;
+    };
+    [key: string]: unknown;
+}
+interface Token {
+    type: string;
+    info?: string;
+    content?: string;
+    map?: number[] | null;
+    children?: Token[] | null;
+}
+interface MarkdownItRenderHost<Tokens> {
+    parse(source: string, env?: unknown): Tokens[];
+    options: unknown;
+    renderer: {
+        render(tokens: Tokens[], options: unknown, env?: unknown): string;
+    };
+}
+export declare function createMarkdownItDraft(options: DraftMarkdownOptions): {
+    plugin: (instance: unknown) => void;
+    prepare: (tokens: Token[], env?: DraftMarkdownItEnvironment) => Promise<DraftDocumentResult>;
+    render: (md: MarkdownItRenderHost<unknown>, source: string, env?: DraftMarkdownItEnvironment) => Promise<{
+        html: string;
+        manifest: DraftDocumentResult;
+    }>;
+};
+export {};

package/dist/types/metadata.d.ts

@@ -0,0 +1,9 @@
+export interface FenceOptions {
+    id?: string;
+    alt?: string;
+    caption?: string;
+    src?: string;
+    mode?: string;
+    state?: string;
+}
+export declare function parseFenceOptions(info: string): FenceOptions;

package/dist/types/remark.d.ts

@@ -0,0 +1,21 @@
+import { type DraftMarkdownOptions } from './core.js';
+interface Node {
+    type: string;
+    lang?: string | null;
+    meta?: string | null;
+    value?: string;
+    children?: Node[];
+    position?: {
+        start?: {
+            line?: number;
+            column?: number;
+        };
+    };
+}
+interface FileLike {
+    path?: string;
+    data?: Record<string, unknown>;
+}
+/** Convert only parser-recognized `draft` code nodes into static image nodes. */
+export default function remarkDraft(options: DraftMarkdownOptions): (tree: Node, file: FileLike) => Promise<void>;
+export {};

package/dist/types/source.d.ts

@@ -0,0 +1,4 @@
+export declare function resolveSource(src: string, documentPath: string, rootDir: string): Promise<{
+    source: string;
+    path: string;
+}>;

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@draftably/markdown",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Build static SVG diagram assets from Markdown draft fences.",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./remark": {
+      "types": "./dist/types/remark.d.ts",
+      "import": "./dist/remark.js"
+    },
+    "./markdown-it": {
+      "types": "./dist/types/markdown-it.d.ts",
+      "import": "./dist/markdown-it.js"
+    },
+    "./files": {
+      "types": "./dist/types/files.d.ts",
+      "import": "./dist/files.js"
+    },
+    "./client": {
+      "types": "./dist/types/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@draftably/runtime": "0.1.0"
+  },
+  "engines": {
+    "node": ">=22.21.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/byronwall/draftably.git",
+    "directory": "packages/markdown"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-markdown.ts",
+    "test": "node ../../scripts/prove-markdown-package.ts"
+  }
 }