@jarenjs/md 0.34.2 → 0.43.3

package/README.md

@@ -276,6 +276,29 @@ createApp(appDoc, {
   source string (or the same parsed document) returns the same vnode
   reference, so the view patcher skips an unchanged article in O(1) —
   the derivation contract `@jarenjs/app` viewModels rely on.
+- `md.view(sourceOrDoc, policy)` renders that one call under a
+  **rendering policy**, for a host whose documents do not all come from
+  the same place. Heading ids are the live case: ids are a page's
+  namespace, so markdown the host authored may mint them bare while
+  markdown from anywhere else renders with a `slugPrefix` —
+
+  ```js
+  const TRUSTED = { slugPrefix: '' };                    // your own documents
+  const UNTRUSTED = { slugPrefix: 'user-content-' };     // everyone else's
+
+  md.view(readme, TRUSTED);          // id="setup"
+  md.view(reply, UNTRUSTED);         // id="user-content-setup"
+  ```
+
+  A policy may name `headingIds`, `slugPrefix`, `headingAnchors`,
+  `footnotesLabel`, `html` and `keyed` — the options that shape the
+  emitted vnode; anything else (`plugins`, `sanitizeUrl` — construction-
+  time decisions, and `plugins` changes the *parse*) is **refused**, not
+  ignored. The projection is memoized per source **and** policy, so
+  alternating provenances cannot thrash the cache and each stays
+  reference-stable; the parse and the hydratable index are shared, which
+  is why this is one component and not two. A call that names no policy
+  renders under the construction-time options, unchanged.
 - `md.effects['md-load']` resolves any URL through the loader (cache,
   abort, streaming) and dispatches the plain `MdDocument` as the
   action payload; `md-parse` does the same for an in-state source
@@ -342,7 +365,7 @@ an editable data pane.
 ### Directives — a number a machine derives and a human reads
 
 ```markdown
-Jaren is <!--bm:jsonpath.ctsRatio-->23.1<!--/bm-->x faster on the CTS mean.
+Jaren is <!--bm:jsonpath.ctsRatio-->8.8<!--/bm-->x faster across the CTS queries.
 ```
 
 Every markdown renderer on earth drops HTML comments, so GitHub, an editor
@@ -416,7 +439,13 @@ as markup or as a live URL.
 
 `options.sanitizeUrl` — `(url) => string | null` — replaces the URL policy
 wholesale when a host needs a custom scheme in trusted content. It is the
-whole guard, so widen it deliberately. Plugin `render` functions shadow the
+whole guard, so widen it deliberately.
+
+Heading ids are the other half of the same question, and it is settled per
+*document* rather than per emitter: a host that renders its own documents
+beside documents it did not author passes the rendering policy to
+`md.view(source, policy)` (above), so untrusted text gets a `slugPrefix`
+and the host's own documents do not. Plugin `render` functions shadow the
 core emitter and own the rule for URLs they emit; `ctx.sanitizeUrl` is the
 active policy ([PLUGINS.md](docs/PLUGINS.md) §5, [MD-FORMAT.md](docs/MD-FORMAT.md) §4.3).
 

package/dist/types/component/index.d.ts

@@ -26,17 +26,45 @@ export type MdComponentOptions = MdCompileOptions & {
     fetch?: typeof globalThis.fetch;
     cache?: any;
     memoLimit?: number;
+    policyLimit?: number;
     onHydrateError?: (err: any) => void;
 };
+export type MdRenderPolicy = {
+    /**
+     * mint an `id` on every heading
+     */
+    headingIds?: boolean;
+    /**
+     * prepended to every emitted heading id
+     * and to the anchor href beside it (`''` opts out)
+     */
+    slugPrefix?: string;
+    /**
+     * emit the copy-a-link anchor
+     */
+    headingAnchors?: boolean;
+    /**
+     * the footnote section's heading
+     */
+    footnotesLabel?: string;
+    /**
+     * what to do with raw HTML
+     */
+    html?: 'skip' | 'text';
+    /**
+     * emit patcher keys on block children
+     */
+    keyed?: boolean;
+};
 export type MdComponent = {
     /**
      * the compiled-in plugin set
      */
     plugins: any[];
     /**
-     * memoized vnode projection
+     *   memoized vnode projection, per source AND policy
      */
-    view: (sourceOrDoc: any) => any;
+    view: (sourceOrDoc: any, policy?: MdRenderPolicy) => any;
     /**
      * memoized compile
      */
@@ -62,14 +90,38 @@ export type MdComponent = {
  *   fetch?: typeof globalThis.fetch,
  *   cache?: any,
  *   memoLimit?: number,
+ *   policyLimit?: number,
  *   onHydrateError?: (err: any) => void,
  * }} MdComponentOptions
  */
+/**
+ * The rendering policy a single `view()` call may name, for a host that
+ * renders documents of different PROVENANCE through one component. Only
+ * the options that shape the emitted vnode belong here — the parse is
+ * provenance-independent, and `plugins`/`sanitizeUrl` are the
+ * construction-time decisions a per-call override would quietly undo.
+ *
+ * The live case is heading ids: repo-authored Markdown is trusted with
+ * the ids it mints, and text from anywhere else must not mint bare ids
+ * into a page that owns ids of its own — so it renders with a
+ * `slugPrefix`. Footnote ids already default to `user-content-`
+ * (MD-FORMAT §4.6) and are unaffected.
+ *
+ * @typedef {object} MdRenderPolicy
+ * @property {boolean} [headingIds] mint an `id` on every heading
+ * @property {string} [slugPrefix] prepended to every emitted heading id
+ *   and to the anchor href beside it (`''` opts out)
+ * @property {boolean} [headingAnchors] emit the copy-a-link anchor
+ * @property {string} [footnotesLabel] the footnote section's heading
+ * @property {'skip'|'text'} [html] what to do with raw HTML
+ * @property {boolean} [keyed] emit patcher keys on block children
+ */
 /**
  * The component bundle.
  * @typedef {object} MdComponent
  * @property {any[]} plugins the compiled-in plugin set
- * @property {(sourceOrDoc: any) => any} view memoized vnode projection
+ * @property {(sourceOrDoc: any, policy?: MdRenderPolicy) => any} view
+ *   memoized vnode projection, per source AND policy
  * @property {(source: string) => CompiledMd} compile memoized compile
  * @property {Record<string, (props: any, dispatch: any) => any>} effects
  *   `md-load` and `md-parse` for `createApp({ effects })`

package/docs/MD-FORMAT.md

@@ -305,7 +305,10 @@ this package's conformance score at odds with the documents it produces.
 
 `mdToVnode` implements this as `headingIds`, `slugPrefix` and
 `headingAnchors`; the slug transform itself is `slugify` from
-`@jarenjs/core/string`, the suite's only one.
+`@jarenjs/core/string`, the suite's only one. A host whose documents do
+not all share one provenance names the prefix per render rather than per
+emitter — the visual component takes the rendering policy as `view()`'s
+second argument (README §"The visual component").
 
 ### 4.6 Footnotes (normative)
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/md",
   "private": false,
-  "version": "0.34.2",
+  "version": "0.43.3",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -73,8 +73,8 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.34.2",
-    "@jarenjs/mermaid": "^0.34.2",
-    "@jarenjs/view": "^0.34.2"
+    "@jarenjs/core": "^0.43.3",
+    "@jarenjs/mermaid": "^0.43.3",
+    "@jarenjs/view": "^0.43.3"
   }
 }

package/src/component/index.js

@@ -20,9 +20,11 @@
  * ARCHITECTURE.md §"Engine and component".
  */
 
+import { createBoundedCache } from '@jarenjs/core/cache';
 import { createProjectionMemo } from '@jarenjs/view/helpers';
 import { buildPluginTables } from '../parser.js';
 import { compileMarkdown } from '../compiler.js';
+import { mdToVnode } from '../to-vnode.js';
 import { loadMarkdown } from '../loader.js';
 import { walkAst } from '../ast.js';
 import { hashContent } from '../utils.js';
@@ -39,14 +41,38 @@ import { highlightPlugin } from '../plugins/highlight.js';
  *   fetch?: typeof globalThis.fetch,
  *   cache?: any,
  *   memoLimit?: number,
+ *   policyLimit?: number,
  *   onHydrateError?: (err: any) => void,
  * }} MdComponentOptions
  */
+/**
+ * The rendering policy a single `view()` call may name, for a host that
+ * renders documents of different PROVENANCE through one component. Only
+ * the options that shape the emitted vnode belong here — the parse is
+ * provenance-independent, and `plugins`/`sanitizeUrl` are the
+ * construction-time decisions a per-call override would quietly undo.
+ *
+ * The live case is heading ids: repo-authored Markdown is trusted with
+ * the ids it mints, and text from anywhere else must not mint bare ids
+ * into a page that owns ids of its own — so it renders with a
+ * `slugPrefix`. Footnote ids already default to `user-content-`
+ * (MD-FORMAT §4.6) and are unaffected.
+ *
+ * @typedef {object} MdRenderPolicy
+ * @property {boolean} [headingIds] mint an `id` on every heading
+ * @property {string} [slugPrefix] prepended to every emitted heading id
+ *   and to the anchor href beside it (`''` opts out)
+ * @property {boolean} [headingAnchors] emit the copy-a-link anchor
+ * @property {string} [footnotesLabel] the footnote section's heading
+ * @property {'skip'|'text'} [html] what to do with raw HTML
+ * @property {boolean} [keyed] emit patcher keys on block children
+ */
 /**
  * The component bundle.
  * @typedef {object} MdComponent
  * @property {any[]} plugins the compiled-in plugin set
- * @property {(sourceOrDoc: any) => any} view memoized vnode projection
+ * @property {(sourceOrDoc: any, policy?: MdRenderPolicy) => any} view
+ *   memoized vnode projection, per source AND policy
  * @property {(source: string) => CompiledMd} compile memoized compile
  * @property {Record<string, (props: any, dispatch: any) => any>} effects
  *   `md-load` and `md-parse` for `createApp({ effects })`
@@ -98,7 +124,7 @@ export function createMdComponent(options = {}) {
     });
   };
 
-  const { compile, view } = createProjectionMemo({
+  const { compile, view: viewDefault } = createProjectionMemo({
     memoLimit,
     compile: (source) => {
       const compiled = compileMarkdown(source, compileOptions);
@@ -113,6 +139,63 @@ export function createMdComponent(options = {}) {
     },
   });
 
+  // One projection memo per named policy, on top of the one compile
+  // memo above: parsing is provenance-independent, so a second policy
+  // costs a second vnode and nothing else. Bounded because a caller
+  // that mints a policy per call would otherwise retain every variant
+  // it ever rendered; a host names two or three provenances, not
+  // hundreds.
+  /** @type {import('@jarenjs/core/cache').BoundedCache<string, any>} */
+  const variants = createBoundedCache(options.policyLimit ?? 8);
+
+  /**
+   * The projection memo for one policy. Reference stability is the whole
+   * contract, so the vnode is cached against the compiled document the
+   * shared memo already returns — `mdToVnode` is called once per
+   * (document, policy), never once per render.
+   * @param {MdRenderPolicy} policy
+   */
+  const buildVariant = (policy) => {
+    const renderOptions = {
+      plugins: compileOptions.plugins,
+      html: compileOptions.html,
+      sanitizeUrl: compileOptions.sanitizeUrl,
+      headingIds: compileOptions.headingIds,
+      slugPrefix: compileOptions.slugPrefix,
+      headingAnchors: compileOptions.headingAnchors,
+      footnotesLabel: compileOptions.footnotesLabel,
+      keyed: compileOptions.keyed,
+      ...policy,
+    };
+    /** @type {WeakMap<any, any>} compiled document → its vnode */
+    const vnodes = new WeakMap();
+    const project = (/** @type {any} */ compiled) => {
+      let vnode = vnodes.get(compiled);
+      if (vnode === undefined) {
+        vnode = mdToVnode(compiled, renderOptions);
+        vnodes.set(compiled, vnode);
+      }
+      return vnode;
+    };
+    return createProjectionMemo({
+      memoLimit,
+      compile,
+      toVnode: project,
+      docToVnode: (doc) => {
+        indexHydratable(doc);
+        return project(compileMarkdown(doc, compileOptions));
+      },
+    });
+  };
+
+  /** @type {MdComponent['view']} */
+  const view = (sourceOrDoc, policy) => {
+    if (policy === undefined || policy === null) return viewDefault(sourceOrDoc);
+    const key = policyKey(policy);
+    if (key === '') return viewDefault(sourceOrDoc);
+    return variants.getOrCreate(key, () => buildVariant(policy)).view(sourceOrDoc);
+  };
+
   /** @type {MdComponent} */
   const component = {
     plugins,
@@ -183,6 +266,38 @@ export function createMdComponent(options = {}) {
   return component;
 }
 
+/**
+ * The option names a per-call {@link MdRenderPolicy} may carry. Anything
+ * else is refused rather than ignored: a policy naming `plugins` would
+ * silently render under the construction-time set, which is exactly the
+ * kind of quiet disagreement the per-call policy exists to end.
+ */
+const POLICY_OPTIONS = new Set([
+  'headingIds', 'slugPrefix', 'headingAnchors', 'footnotesLabel', 'html', 'keyed',
+]);
+
+/**
+ * A policy's cache key: its members in name order, so two spellings of
+ * the same policy share one memo. An empty key means the policy named
+ * nothing and the construction-time defaults answer it.
+ * @param {MdRenderPolicy} policy
+ * @returns {string}
+ * @throws {TypeError} when the policy names an option it may not set.
+ */
+function policyKey(policy) {
+  let key = '';
+  for (const name of Object.keys(policy).sort()) {
+    if (!POLICY_OPTIONS.has(name)) {
+      throw new TypeError(`md view policy: '${name}' is not a rendering option `
+        + `(${[...POLICY_OPTIONS].join(', ')})`);
+    }
+    const value = /** @type {any} */ (policy)[name];
+    if (value === undefined) continue;
+    key += `${name}=${JSON.stringify(value)};`;
+  }
+  return key;
+}
+
 /**
  * The component's default plugin set: syntax highlighting on. A single
  * shared array so `buildPluginTables` (and every memo hanging off it)