@aiquants/markdown-explorer 0.0.0-stage → 0.2.0

package/dist/sanitizeWorker.js

@@ -0,0 +1,281 @@
+import { parentPort as ee } from "node:worker_threads";
+import { defaultTreeAdapter as b, parse as te, html as re } from "parse5";
+import { allowedFrameUrlOf as ne, reduceFrameFeatures as oe, EMBED_FRAME_REFERRER_POLICIES as se, EMBED_LINK_ATTRIBUTE as H, placeholderLinkOf as ae } from "@aiquants/markdown/embeds";
+import S from "isomorphic-dompurify";
+import { i as ie, e as ce } from "./dataRoute-Bkfwfp1R.js";
+const F = 512, le = 4096, G = 1024, j = /* @__PURE__ */ Symbol("placement"), V = 2, ue = 3, fe = /* @__PURE__ */ new Set(["html", "head", "body"]), w = 0, D = 1, M = 2, W = 3, z = 4, O = 5, k = 6, N = 7, Q = 8, I = 9, $ = 10, _ = -1, de = 0, pe = 1, Ee = 2, me = 3, he = 4, Te = 5, K = 6, Ae = 7, ge = (t) => {
+  switch (t) {
+    case 9:
+    case 10:
+    case 12:
+    case 13:
+    case 32:
+      return de;
+    case 47:
+      return pe;
+    case 62:
+      return Ee;
+    case 61:
+      return me;
+    case 34:
+      return he;
+    case 39:
+      return Te;
+    default:
+      return K;
+  }
+}, Se = Uint8Array.from({ length: 128 }, (t, i) => ge(i)), v = 60, X = 47, _e = /[\t\n\f\r />="'<]/g, we = /["<]/g, be = /['<]/g, A = -1 - M, Ne = Int8Array.from(
+  [
+    [D, I, _, w, w, w, w],
+    [D, I, _, A, A, A, A],
+    [W, I, _, z, M, M, M],
+    [W, I, _, z, A, A, A],
+    [z, N, _, N, O, k, N],
+    [O, O, O, O, Q, O, O],
+    [k, k, k, k, k, Q, k],
+    [D, N, _, N, N, N, N],
+    [D, I, _, A, A, A, A],
+    [D, I, _, A, A, A, A]
+  ].flat()
+), J = (t) => t >= 65 && t <= 90 || t >= 97 && t <= 122, Oe = (t, i) => {
+  let u = new Int32Array($), f = new Int32Array($), c = 0, h = 0, n = 0;
+  for (; n < t.length; ) {
+    if (c === 0) {
+      const p = t.indexOf("<", n);
+      if (p < 0) return !1;
+      n = p + 1, t.charCodeAt(n) === X && (n += 1), J(t.charCodeAt(n)) && (u[w] = 0, c = 1 << w, n += 1);
+      continue;
+    }
+    if ((c & -230) === 0 && n >= h) {
+      const p = c === 1 << O ? we : c === 1 << k ? be : _e;
+      p.lastIndex = n;
+      const a = p.exec(t);
+      if (a === null) return !1;
+      n = a.index, t.charCodeAt(n) === v && (h = n + 3);
+    }
+    const m = t.charCodeAt(n), g = m < 128 ? Se[m] : K;
+    let T = 0;
+    for (let p = c; p !== 0; p &= p - 1) {
+      const a = 31 - Math.clz32(p & -p);
+      let r = Ne[a * Ae + g], o = u[a];
+      if (r < _ && (r = -1 - r, o += 1, o > i))
+        return !0;
+      if (r === _) continue;
+      const E = 1 << r;
+      ((T & E) === 0 || o > f[r]) && (f[r] = o), T |= E;
+    }
+    J(m) && (t.charCodeAt(n - 1) === v || t.charCodeAt(n - 1) === X && t.charCodeAt(n - 2) === v) && (T & 1 << w) === 0 && (f[w] = 0, T |= 1 << w);
+    const L = u;
+    u = f, f = L, c = T, n += 1;
+  }
+  return !1;
+};
+class C extends Error {
+  status;
+  constructor(i) {
+    super(`[markdown-explorer] the nesting guard stopped the parse: ${i}`), this.name = "ParseStop", this.status = i;
+  }
+}
+const ke = (t, i, u, f) => {
+  if (!Number.isSafeInteger(i) || i <= 0) throw new RangeError(`[markdown-explorer] the nesting guard's depth limit must be a positive safe integer; got ${String(i)}`);
+  if (!Number.isSafeInteger(u) || u <= 0) throw new RangeError(`[markdown-explorer] the nesting guard's node budget must be a positive safe integer; got ${String(u)}`);
+  if (!Number.isSafeInteger(f) || f <= 0) throw new RangeError(`[markdown-explorer] the nesting guard's attribute character budget must be a positive safe integer; got ${String(f)}`);
+  if (Oe(t, G)) return { status: "too-many-attributes" };
+  const c = i + V, h = t.length + ue;
+  let n = null, m = 0, g = 0, T = 0, L = 0;
+  const p = (e) => {
+    if (g += e, g > u) throw new C("too-many-nodes");
+  }, a = (e) => {
+    for (const s of e) L += s.name.length + s.value.length;
+    if (L > f) throw new C("too-many-attribute-characters");
+  }, r = (e, s, l, d) => {
+    const P = { node: e, above: null, levels: s, height: 0, keepsChildren: l, attributes: d, first: null, next: null, previous: null }, Z = e;
+    return Z[j] = P, P;
+  }, o = (e) => {
+    const l = e[j];
+    if (l === void 0) throw new Error("[markdown-explorer] the nesting guard was handed a node it did not create");
+    return l;
+  }, E = (e, s) => {
+    let l = s;
+    for (let d = e; d !== null && l > d.height; d = d.above)
+      d.height = l, l += d.levels;
+    if (n !== null && n.height > c) throw new C("too-deep");
+  }, y = (e) => {
+    const s = e.above;
+    s?.keepsChildren && (e.previous === null ? s.first = e.next : e.previous.next = e.next, e.next !== null && (e.next.previous = e.previous)), e.above = null, e.next = null, e.previous = null;
+  }, R = (e, s) => {
+    if (!b.isElementNode(s)) return;
+    const l = o(s), d = o(e);
+    y(l), l.above = d, d.keepsChildren && (l.next = d.first, d.first !== null && (d.first.previous = l), d.first = l), s.parentNode = e, E(d, l.height + l.levels);
+  }, x = {
+    ...b,
+    createDocument: () => {
+      const e = b.createDocument();
+      return n = r(e, 0, !1, 0), e;
+    },
+    createDocumentFragment: () => {
+      const e = b.createDocumentFragment();
+      return r(e, 0, !1, 0), e;
+    },
+    createElement: (e, s, l) => {
+      if (m += 1, m > h) throw new C("too-many-elements");
+      p(1 + l.length), a(l);
+      const d = b.createElement(e, s, l);
+      return r(d, 1, !(s === re.NS.HTML && fe.has(e)), l.length), d;
+    },
+    createCommentNode: (e) => {
+      if (T += 1, T > le) throw new C("too-many-comments");
+      return p(1), b.createCommentNode(e);
+    },
+    setTemplateContent: (e, s) => {
+      b.setTemplateContent(e, s);
+      const l = o(s);
+      l.above = o(e), E(l.above, l.height);
+    },
+    appendChild: R,
+    insertBefore: (e, s) => R(e, s),
+    detachNode: (e) => {
+      b.isElementNode(e) && (y(o(e)), e.parentNode = null);
+    },
+    getFirstChild: (e) => {
+      const s = o(e);
+      if (!s.keepsChildren) throw new Error("[markdown-explorer] the nesting guard was asked for the children of a node whose children it does not keep");
+      return s.first === null ? null : s.first.node;
+    },
+    getChildNodes: () => {
+      throw new Error("[markdown-explorer] the nesting guard keeps no child lists for source locations");
+    },
+    onItemPop: (e) => {
+      const s = o(e);
+      s.keepsChildren = !1, s.first = null;
+    },
+    insertText: () => {
+    },
+    insertTextBefore: () => {
+    },
+    adoptAttributes: (e, s) => {
+      p(s.length), a(s);
+      const l = o(e);
+      if (l.attributes += s.length, l.attributes > G) throw new C("too-many-attributes");
+    }
+  };
+  let B;
+  try {
+    B = te(t, { scriptingEnabled: !1, treeAdapter: x });
+  } catch (e) {
+    if (e instanceof C) return { status: e.status };
+    throw e;
+  }
+  return { status: "within", depth: o(B).height - V, elements: m, nodes: g };
+};
+class Y extends RangeError {
+  constructor(i) {
+    super(`[markdown-explorer] the HTML nests deeper than ${String(i)} levels`), this.name = "HtmlNestingLimitError";
+  }
+}
+const Ce = ["script", "style", "noscript", "template", "form", "button", "textarea", "select", "option", "object", "embed", "base", "meta", "link", "frame", "frameset"], Le = ["srcdoc", "formaction"], Re = /^(?:(?:https?|mailto|tel):|[^a-z]|[a-z+.-]+(?:[^a-z+.:-]|$))/iu, Ie = /* @__PURE__ */ new Set(["left", "right", "center", "justify", "start", "end"]), ye = /* @__PURE__ */ new Set(["h1", "h2", "h3", "h4", "h5", "h6"]), U = 1, De = 3, Me = 7, Ue = 8, q = Object.freeze({
+  a: Object.freeze(["target", "data-link-kind", "data-doc-path", "data-doc-exists", "data-footnote-ref", "data-footnote-backref"]),
+  area: Object.freeze(["target"]),
+  img: Object.freeze(["data-asset-src", "data-asset-exists"]),
+  section: Object.freeze(["data-footnotes"]),
+  iframe: Object.freeze(["allow", "allowfullscreen", "frameborder", "referrerpolicy"])
+}), xe = [...new Set(Object.values(q).flatMap((t) => t.filter((i) => i.startsWith("data-"))))], He = /* @__PURE__ */ new Set(["src", "href", "xlink:href"]), ze = /^data:/iu, ve = Object.freeze({
+  FORBID_TAGS: Ce,
+  FORBID_ATTR: Le,
+  ADD_TAGS: ["iframe"],
+  ADD_ATTR: (t, i) => q[i]?.includes(t) === !0,
+  ADD_URI_SAFE_ATTR: xe,
+  ALLOWED_URI_REGEXP: Re,
+  ALLOW_DATA_ATTR: !1
+}), Be = (t) => {
+  let i = null;
+  for (const u of t.split(";")) {
+    const f = u.indexOf(":");
+    if (f < 0 || u.slice(0, f).trim().toLowerCase() !== "text-align") continue;
+    const c = u.slice(f + 1).trim().toLowerCase();
+    Ie.has(c) && (i = c);
+  }
+  return i === null ? null : `text-align: ${i}`;
+}, Pe = (t) => t.nodeType === De ? { kind: "text", text: t.nodeValue ?? "" } : t.nodeType === Ue || t.nodeType === Me ? { kind: "ignored" } : t.nodeType === U && t.nodeName.toLowerCase() === "a" ? { kind: "link", href: t.getAttribute("href") } : { kind: "element" }, Fe = (t) => {
+  const i = t.getAttribute("type");
+  return i !== null && i.trim().toLowerCase() === "checkbox" && t.hasAttribute("disabled");
+}, Ge = (t, i, u) => {
+  if (S.isSupported !== !0) throw new Error("[markdown-explorer] the HTML sanitizer cannot run in this environment");
+  if (!Number.isSafeInteger(u) || u <= 0) throw new RangeError(`[markdown-explorer] the HTML sanitizer's depth limit must be a positive integer; got ${String(u)}`);
+  const f = Object.freeze([...t]);
+  let c = /* @__PURE__ */ new WeakMap(), h = /* @__PURE__ */ new WeakMap();
+  const n = (a) => {
+    const r = a.parentNode === null ? void 0 : c.get(a.parentNode), o = r === void 0 ? 0 : r + 1;
+    if (c.set(a, o), a.nodeType === U && o > u) throw new Y(u);
+  }, m = (a, r) => {
+    if (a.nodeType !== U) return;
+    const o = a;
+    (r.tagName === "input" && !Fe(o) || r.tagName === "iframe" && ne(o.getAttribute("src")?.trim(), f) === null) && o.parentNode?.removeChild(o);
+  }, g = (a, r) => {
+    const o = a.nodeName.toLowerCase();
+    if (r.attrName === "style") {
+      const E = Be(r.attrValue);
+      E === null ? r.keepAttr = !1 : r.attrValue = E;
+    } else if (r.attrName === "allow" && o === "iframe") {
+      const E = oe(r.attrValue);
+      E === null ? r.keepAttr = !1 : r.attrValue = E;
+    } else if (r.attrName === "referrerpolicy" && o === "iframe") {
+      const E = r.attrValue.trim().toLowerCase();
+      se.has(E) ? r.attrValue = E : r.keepAttr = !1;
+    } else r.attrName === H && o === "p" ? h.set(a, a.getAttribute(H)) : He.has(r.attrName) && ze.test(r.attrValue) ? r.keepAttr = !1 : r.attrName === "id" && ye.has(o) && (r.forceKeepAttr = !0);
+  }, T = (a) => {
+    const r = a.getAttribute("data-asset-src");
+    r !== null && (a.getAttribute("data-asset-exists") !== "false" && ie(r) ? a.setAttribute("src", ce(i, r, null)) : a.removeAttribute("src"));
+  }, L = (a) => {
+    const r = a.parentNode;
+    if (r === null) return;
+    const o = h.get(r);
+    o != null && ae(o, [...r.childNodes].map(Pe)) !== null && r.setAttribute(H, o);
+  }, p = (a) => {
+    if (a.nodeType !== U) return;
+    const r = a, o = r.nodeName.toLowerCase();
+    o === "img" ? T(r) : o === "a" && L(r);
+    const E = r.getAttribute("target");
+    if (E === null || E.trim().toLowerCase() === "_self") return;
+    const y = r.getAttribute("rel"), R = new Set(y === null ? [] : y.split(/\s+/u).filter((x) => x !== ""));
+    R.add("noopener"), R.add("noreferrer"), r.setAttribute("rel", [...R].join(" "));
+  };
+  return (a) => {
+    c = /* @__PURE__ */ new WeakMap(), h = /* @__PURE__ */ new WeakMap(), S.addHook("beforeSanitizeElements", n), S.addHook("uponSanitizeElement", m), S.addHook("uponSanitizeAttribute", g), S.addHook("afterSanitizeAttributes", p);
+    try {
+      return S.sanitize(a, ve);
+    } finally {
+      S.removeHook("beforeSanitizeElements", n), S.removeHook("uponSanitizeElement", m), S.removeHook("uponSanitizeAttribute", g), S.removeHook("afterSanitizeAttributes", p);
+    }
+  };
+}, je = (t) => {
+  if (t === null || typeof t != "object") return !1;
+  const { id: i, input: u } = t;
+  if (typeof i != "number" || u === null || typeof u != "object") return !1;
+  const { html: f, iframeHosts: c, dataPath: h, maxNodes: n, maxAttributeChars: m, maxSanitizedChars: g } = u;
+  return typeof f == "string" && Array.isArray(c) && c.every((T) => typeof T == "string") && typeof h == "string" && h !== "" && [n, m, g].every((T) => Number.isSafeInteger(T) && T > 0);
+}, Ve = () => {
+  const t = ee;
+  if (t === null) throw new Error("[markdown-explorer] the sanitizer worker must run in a worker thread");
+  const i = /* @__PURE__ */ new Map();
+  t.on("message", (u) => {
+    if (!je(u)) throw new TypeError("[markdown-explorer] the sanitizer worker received a message that is not a job");
+    const { id: f, input: c } = u;
+    let h;
+    try {
+      if (ke(c.html, F, c.maxNodes, c.maxAttributeChars).status !== "within") {
+        t.postMessage({ id: f, output: { status: "too-large" } });
+        return;
+      }
+      const n = JSON.stringify([c.iframeHosts, c.dataPath]);
+      let m = i.get(n);
+      m === void 0 && (m = Ge(c.iframeHosts, c.dataPath, F), i.set(n, m));
+      const g = m(c.html);
+      h = g.length > c.maxSanitizedChars ? { status: "too-large" } : { status: "sanitized", html: g };
+    } catch (n) {
+      h = n instanceof Y ? { status: "too-large" } : { status: "error", message: n instanceof Error ? `${n.name}: ${n.message}` : String(n) };
+    }
+    t.postMessage({ id: f, output: h });
+  }), t.postMessage({ ready: !0 });
+};
+Ve();

package/dist/server/anonymous.d.cts

@@ -0,0 +1,10 @@
+import { ExplorerAuthentication } from "./ports.cjs";
+export type AnonymousPrincipal = {
+    readonly kind: "anonymous";
+};
+export type AnonymousAccess = {
+    readonly authenticate: (request: Request) => Promise<ExplorerAuthentication<AnonymousPrincipal>>;
+    readonly principalKey: (principal: AnonymousPrincipal) => string;
+    readonly signedOutPage: (request: Request, headers: Headers) => Response;
+};
+export declare const anonymousAccess: AnonymousAccess;

package/dist/server/anonymous.d.ts

@@ -0,0 +1,10 @@
+import { ExplorerAuthentication } from "./ports.js";
+export type AnonymousPrincipal = {
+    readonly kind: "anonymous";
+};
+export type AnonymousAccess = {
+    readonly authenticate: (request: Request) => Promise<ExplorerAuthentication<AnonymousPrincipal>>;
+    readonly principalKey: (principal: AnonymousPrincipal) => string;
+    readonly signedOutPage: (request: Request, headers: Headers) => Response;
+};
+export declare const anonymousAccess: AnonymousAccess;

package/dist/server/createMarkdownExplorer.d.cts

@@ -0,0 +1,12 @@
+import { HeadersFunction } from "react-router";
+import { MarkdownExplorerServer, MarkdownExplorerServerConfig } from "./ports.cjs";
+export declare const DEFAULT_DEFERRED_TIMEOUT_MS = 4000;
+export declare const DEFAULT_TREE_CACHE: Readonly<{
+    ttlMs: 300000;
+    maxEntries: 64;
+    maxBytes: number;
+}>;
+export declare const MIN_SCOPE_SECRET_LENGTH = 32;
+export declare const EXPLORER_DATA_RESPONSE_HEADERS: Readonly<Record<string, string>>;
+export declare const carryLoaderHeaders: HeadersFunction;
+export declare const createMarkdownExplorer: <P>(serverConfig: MarkdownExplorerServerConfig<P>) => MarkdownExplorerServer;

package/dist/server/createMarkdownExplorer.d.ts

@@ -0,0 +1,12 @@
+import { HeadersFunction } from "react-router";
+import { MarkdownExplorerServer, MarkdownExplorerServerConfig } from "./ports.js";
+export declare const DEFAULT_DEFERRED_TIMEOUT_MS = 4000;
+export declare const DEFAULT_TREE_CACHE: Readonly<{
+    ttlMs: 300000;
+    maxEntries: 64;
+    maxBytes: number;
+}>;
+export declare const MIN_SCOPE_SECRET_LENGTH = 32;
+export declare const EXPLORER_DATA_RESPONSE_HEADERS: Readonly<Record<string, string>>;
+export declare const carryLoaderHeaders: HeadersFunction;
+export declare const createMarkdownExplorer: <P>(serverConfig: MarkdownExplorerServerConfig<P>) => MarkdownExplorerServer;

package/dist/server/errors.d.cts

@@ -0,0 +1,26 @@
+import { ExplorerFailure, ExplorerFailureReason } from "../core/contracts.cjs";
+export type ExplorerOperation = "authenticate" | "tree" | "children" | "document" | "notices" | "refresh" | "boundary" | "asset";
+export type ExplorerLogDetail = {
+    readonly operation: ExplorerOperation;
+    readonly sourceId?: string;
+    readonly path?: string;
+    readonly error: unknown;
+};
+export type ExplorerLogger = {
+    readonly error: (message: string, detail: ExplorerLogDetail) => void;
+};
+export declare const DEFAULT_EXPLORER_LOGGER: ExplorerLogger;
+export declare class ExplorerError extends Error {
+    readonly reason: ExplorerFailureReason;
+    readonly code: string | undefined;
+    constructor(reason: ExplorerFailureReason, options?: {
+        readonly code?: string;
+        readonly cause?: unknown;
+    });
+}
+export declare const isAbortError: (error: unknown) => boolean;
+export declare const reportFailure: (logger: ExplorerLogger, detail: ExplorerLogDetail) => void;
+export declare const reportDroppedEntry: (logger: ExplorerLogger, detail: ExplorerLogDetail) => void;
+export declare const reportDeniedRequest: (logger: ExplorerLogger, detail: Omit<ExplorerLogDetail, "error">) => void;
+export declare const observeRejection: (answer: unknown, report: (error: unknown) => void) => void;
+export declare const failureFromError: (error: unknown, detail: Omit<ExplorerLogDetail, "error">, signal: AbortSignal, logger: ExplorerLogger) => ExplorerFailure;

package/dist/server/errors.d.ts

@@ -0,0 +1,26 @@
+import { ExplorerFailure, ExplorerFailureReason } from "../core/contracts.js";
+export type ExplorerOperation = "authenticate" | "tree" | "children" | "document" | "notices" | "refresh" | "boundary" | "asset";
+export type ExplorerLogDetail = {
+    readonly operation: ExplorerOperation;
+    readonly sourceId?: string;
+    readonly path?: string;
+    readonly error: unknown;
+};
+export type ExplorerLogger = {
+    readonly error: (message: string, detail: ExplorerLogDetail) => void;
+};
+export declare const DEFAULT_EXPLORER_LOGGER: ExplorerLogger;
+export declare class ExplorerError extends Error {
+    readonly reason: ExplorerFailureReason;
+    readonly code: string | undefined;
+    constructor(reason: ExplorerFailureReason, options?: {
+        readonly code?: string;
+        readonly cause?: unknown;
+    });
+}
+export declare const isAbortError: (error: unknown) => boolean;
+export declare const reportFailure: (logger: ExplorerLogger, detail: ExplorerLogDetail) => void;
+export declare const reportDroppedEntry: (logger: ExplorerLogger, detail: ExplorerLogDetail) => void;
+export declare const reportDeniedRequest: (logger: ExplorerLogger, detail: Omit<ExplorerLogDetail, "error">) => void;
+export declare const observeRejection: (answer: unknown, report: (error: unknown) => void) => void;
+export declare const failureFromError: (error: unknown, detail: Omit<ExplorerLogDetail, "error">, signal: AbortSignal, logger: ExplorerLogger) => ExplorerFailure;

package/dist/server/fileSystemSource.d.cts

@@ -0,0 +1,38 @@
+import { ExplorerFailureReason, ExplorerHeading } from "../core/contracts.cjs";
+import { ExplorerPathRules } from "../core/paths.cjs";
+import { ExplorerAssetFile, ExplorerHostDocument, ExplorerSource, ExplorerSourceContext } from "./ports.cjs";
+export type FileSystemSkipReason = "not-nfc" | "colon" | "trailing-dot-or-space" | "control-character-or-backslash" | "path-too-long" | "symbolic-link" | "special-file" | "unreadable-directory";
+export type FileSystemSkippedEntry = {
+    readonly sourceId: string;
+    readonly path: string;
+    readonly reason: FileSystemSkipReason;
+};
+export type FileSystemSourceOptions = {
+    readonly id: string;
+    readonly label: string;
+    readonly root: string;
+    readonly pathPrefix: string;
+    readonly parse: (markdown: string, docPath: string) => Promise<{
+        readonly htmlContent: string;
+        readonly headings: readonly ExplorerHeading[];
+    }>;
+    readonly deny?: ExplorerPathRules | false;
+    readonly maxEntries?: number;
+    readonly maxDocumentBytes?: number;
+    readonly textPreviewBytes?: number;
+    readonly walkConcurrency?: number;
+    readonly cacheScope?: "principal" | "shared";
+    readonly reportSkipped?: (skipped: FileSystemSkippedEntry) => void;
+};
+export type FileSystemSource = ExplorerSource<unknown> & {
+    readonly document: (context: ExplorerSourceContext<unknown>, path: string, readPath: string) => Promise<ExplorerHostDocument>;
+    readonly asset: (context: ExplorerSourceContext<unknown>, path: string, readPath: string) => Promise<ExplorerAssetFile>;
+};
+export declare const FILE_SYSTEM_SOURCE_DEFAULTS: Readonly<{
+    maxEntries: 20000;
+    maxDocumentBytes: number;
+    textPreviewBytes: number;
+    walkConcurrency: 8;
+}>;
+export declare const reasonOfFileError: (error: unknown) => ExplorerFailureReason | null;
+export declare const createFileSystemSource: (options: FileSystemSourceOptions) => FileSystemSource;

package/dist/server/fileSystemSource.d.ts

@@ -0,0 +1,38 @@
+import { ExplorerFailureReason, ExplorerHeading } from "../core/contracts.js";
+import { ExplorerPathRules } from "../core/paths.js";
+import { ExplorerAssetFile, ExplorerHostDocument, ExplorerSource, ExplorerSourceContext } from "./ports.js";
+export type FileSystemSkipReason = "not-nfc" | "colon" | "trailing-dot-or-space" | "control-character-or-backslash" | "path-too-long" | "symbolic-link" | "special-file" | "unreadable-directory";
+export type FileSystemSkippedEntry = {
+    readonly sourceId: string;
+    readonly path: string;
+    readonly reason: FileSystemSkipReason;
+};
+export type FileSystemSourceOptions = {
+    readonly id: string;
+    readonly label: string;
+    readonly root: string;
+    readonly pathPrefix: string;
+    readonly parse: (markdown: string, docPath: string) => Promise<{
+        readonly htmlContent: string;
+        readonly headings: readonly ExplorerHeading[];
+    }>;
+    readonly deny?: ExplorerPathRules | false;
+    readonly maxEntries?: number;
+    readonly maxDocumentBytes?: number;
+    readonly textPreviewBytes?: number;
+    readonly walkConcurrency?: number;
+    readonly cacheScope?: "principal" | "shared";
+    readonly reportSkipped?: (skipped: FileSystemSkippedEntry) => void;
+};
+export type FileSystemSource = ExplorerSource<unknown> & {
+    readonly document: (context: ExplorerSourceContext<unknown>, path: string, readPath: string) => Promise<ExplorerHostDocument>;
+    readonly asset: (context: ExplorerSourceContext<unknown>, path: string, readPath: string) => Promise<ExplorerAssetFile>;
+};
+export declare const FILE_SYSTEM_SOURCE_DEFAULTS: Readonly<{
+    maxEntries: 20000;
+    maxDocumentBytes: number;
+    textPreviewBytes: number;
+    walkConcurrency: 8;
+}>;
+export declare const reasonOfFileError: (error: unknown) => ExplorerFailureReason | null;
+export declare const createFileSystemSource: (options: FileSystemSourceOptions) => FileSystemSource;

package/dist/server/ports.d.cts

@@ -0,0 +1,107 @@
+import { ActionFunctionArgs, data, HeadersFunction, LoaderFunctionArgs } from "react-router";
+import { ExplorerConfig } from "../core/config.cjs";
+import { ExplorerEntry, ExplorerFailureDocument, ExplorerHeading, ExplorerMediaType, ExplorerNotice, ExplorerPageData } from "../core/contracts.cjs";
+import { ExplorerPathRules } from "../core/paths.cjs";
+import { ExplorerLogger } from "./errors.cjs";
+import { HtmlSanitizerOptions } from "./sanitizer.cjs";
+export type ExplorerAuthentication<P> = {
+    readonly status: "signed-in";
+    readonly principal: P;
+    readonly headers?: HeadersInit;
+} | {
+    readonly status: "signed-out";
+    readonly headers?: HeadersInit;
+} | {
+    readonly status: "forbidden";
+    readonly headers?: HeadersInit;
+};
+export type ExplorerSourceContext<P> = {
+    readonly principal: P;
+    readonly request: Request;
+    readonly signal: AbortSignal;
+    readonly refresh: boolean;
+};
+export type ExplorerBoundaryAnswer = {
+    readonly inside: false;
+} | {
+    readonly inside: true;
+    readonly readPath: string;
+};
+export type ExplorerSourceBoundary<P> = {
+    readonly contains: (path: string) => boolean;
+    readonly confirm?: (context: ExplorerSourceContext<P>, path: string) => Promise<ExplorerBoundaryAnswer>;
+};
+export type ExplorerSource<P> = {
+    readonly id: string;
+    readonly label: string | ((principal: P) => string);
+    readonly boundary: ExplorerSourceBoundary<P>;
+    readonly tree: (context: ExplorerSourceContext<P>) => Promise<readonly ExplorerEntry[]>;
+    readonly children?: (context: ExplorerSourceContext<P>, path: string, readPath: string) => Promise<readonly ExplorerEntry[]>;
+    readonly cacheScope?: "principal" | "shared";
+};
+export type ExplorerByteRange = {
+    readonly offset: number;
+    readonly length: number;
+};
+export type ExplorerAssetFile = {
+    readonly name: string;
+    readonly contentType: string;
+    readonly size: number | null;
+    readonly version: string;
+    readonly open: (range: ExplorerByteRange | null) => Promise<ReadableStream<Uint8Array>>;
+};
+export type ExplorerHostDocument = {
+    readonly kind: "markdown";
+    readonly name: string;
+    readonly htmlContent: string;
+    readonly headings: readonly ExplorerHeading[];
+} | {
+    readonly kind: "text";
+    readonly name: string;
+    readonly text: string;
+    readonly truncated: boolean;
+    readonly version: string;
+} | {
+    readonly kind: "image";
+    readonly name: string;
+    readonly version: string;
+} | {
+    readonly kind: "media";
+    readonly name: string;
+    readonly mediaType: ExplorerMediaType;
+    readonly version: string;
+} | {
+    readonly kind: "file";
+    readonly name: string;
+    readonly version: string;
+} | ExplorerFailureDocument;
+export type MarkdownExplorerServerConfig<P> = {
+    readonly config: ExplorerConfig;
+    readonly authenticate: (request: Request) => Promise<ExplorerAuthentication<P>>;
+    readonly principalKey: (principal: P) => string;
+    readonly scopeSecret: string;
+    readonly sources: readonly ExplorerSource<P>[];
+    readonly document: (context: ExplorerSourceContext<P>, path: string, readPath: string) => Promise<ExplorerHostDocument>;
+    readonly asset: (context: ExplorerSourceContext<P>, path: string, readPath: string) => Promise<ExplorerAssetFile>;
+    readonly signedOutPage: (request: Request, headers: Headers) => Response;
+    readonly forbiddenPage?: (request: Request, headers: Headers) => Response;
+    readonly notices?: (context: ExplorerSourceContext<P>) => Promise<readonly ExplorerNotice[]>;
+    readonly deny?: ExplorerPathRules | false;
+    readonly treeCache?: {
+        readonly ttlMs?: number;
+        readonly maxEntries?: number;
+        readonly maxBytes?: number;
+    } | false;
+    readonly sanitizer?: HtmlSanitizerOptions;
+    readonly deferredTimeoutMs?: number;
+    readonly logger?: ExplorerLogger;
+    readonly onTreeRefreshed?: (key: string) => void;
+};
+export type ExplorerPageLoaderResult = ReturnType<typeof data<ExplorerPageData>>;
+export type MarkdownExplorerServer = {
+    readonly loader: (args: LoaderFunctionArgs) => Promise<ExplorerPageLoaderResult>;
+    readonly headers: HeadersFunction;
+    readonly dataLoader: (args: LoaderFunctionArgs) => Promise<Response>;
+    readonly dataAction: (args: ActionFunctionArgs) => Promise<Response>;
+    readonly forgetTree: (key: string) => void;
+};