@cube-drone/marquee-html-renderer 0.7.2 → 0.8.0

package/README.md

@@ -13,7 +13,11 @@ const html = render(parse(source)); // a <div class="mq-doc"> fragment
 
 Embedder policy — which schemes link, how media resolves, what turbolinks become, custom
 directive/span vocabulary — is injected via the `Profile` interface; `bareWebProfile` is the
-conservative default. Pair the output with
+conservative default. The `directive`/`span` hooks (a span is the inline twin of a directive)
+are also called by the React renderer and the CodeMirror live preview, so they carry a
+contract, documented on the interface and in the spec: claim on name and attrs alone (a probe
+with empty children answers the same), stay pure and fetchless, and always place the rendered
+children. Pair the output with
 [`@cube-drone/marquee-css`](https://www.npmjs.com/package/@cube-drone/marquee-css) (the `mq-*`
 class contract this renderer targets) and optionally
 [`@cube-drone/marquee-fonts`](https://www.npmjs.com/package/@cube-drone/marquee-fonts).

package/dist/profile.d.ts

@@ -36,9 +36,24 @@ export interface Profile {
      * policy); an explicit `level=` on `:::turbolink` wins over this. */
     turbolinkLevel(target: string): TurbolinkLevel;
     /** Embedder directive vocabulary (widgets, includes, computed). Return
-     * rendered HTML, or null to fall through to the built-in handling. */
+     * rendered HTML, or null to fall through to the built-in handling.
+     *
+     * The contract (spec: "The vocabulary hooks' contract"), because editors
+     * and the React renderer call this too, not just the page render:
+     * - Claim on `name` and `attrs` alone: whether this returns null MUST NOT
+     *   depend on `renderedChildren`. Callers may probe with "" to ask "is
+     *   this yours?" and render for real afterwards.
+     * - Pure, sync, fetchless, cheap: it may run per keystroke, and twice in
+     *   one render, and must answer the same each time.
+     * - Place the children: a claiming answer MUST include `renderedChildren`
+     *   (already-escaped HTML) or a known substitute for them - the shrug's
+     *   never-eat-content rule binds embedder vocabulary too.
+     * Embedder-first: a claim on a name the language defines wins. */
     directive(name: string, attrs: Attrs, renderedChildren: string): string | null;
-    /** Embedder span vocabulary. Same contract as `directive`. */
+    /** Embedder span vocabulary - the inline twin of `directive`
+     * (`[user id=x]Name[/user]` is to `:::user id=x:::` what `[spoiler]` is
+     * to `:::spoiler`). Same contract as `directive`, including the probe:
+     * the live editor asks with "" to decide whether to draw the span whole. */
     span(name: string, attrs: Attrs, renderedChildren: string): string | null;
 }
 /** The bare-web default: https links, extension-sniffed media, no widgets,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cube-drone/marquee-html-renderer",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "Reference static HTML renderer for the Marquee markup language",
   "license": "MPL-2.0",
   "repository": {
@@ -35,12 +35,12 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@cube-drone/marquee-parser": "^0.7.2"
+    "@cube-drone/marquee-parser": "^0.8.0"
   },
   "devDependencies": {
-    "@cube-drone/marquee-css": "^0.7.2",
-    "@cube-drone/marquee-fonts": "^0.7.2",
-    "@cube-drone/marquee-turbolink": "^0.7.2",
+    "@cube-drone/marquee-css": "^0.8.0",
+    "@cube-drone/marquee-fonts": "^0.8.0",
+    "@cube-drone/marquee-turbolink": "^0.8.0",
     "@types/node": "^24.0.0",
     "typescript": "^5.9.0"
   }

package/src/profile.ts

@@ -42,9 +42,24 @@ export interface Profile {
    * policy); an explicit `level=` on `:::turbolink` wins over this. */
   turbolinkLevel(target: string): TurbolinkLevel;
   /** Embedder directive vocabulary (widgets, includes, computed). Return
-   * rendered HTML, or null to fall through to the built-in handling. */
+   * rendered HTML, or null to fall through to the built-in handling.
+   *
+   * The contract (spec: "The vocabulary hooks' contract"), because editors
+   * and the React renderer call this too, not just the page render:
+   * - Claim on `name` and `attrs` alone: whether this returns null MUST NOT
+   *   depend on `renderedChildren`. Callers may probe with "" to ask "is
+   *   this yours?" and render for real afterwards.
+   * - Pure, sync, fetchless, cheap: it may run per keystroke, and twice in
+   *   one render, and must answer the same each time.
+   * - Place the children: a claiming answer MUST include `renderedChildren`
+   *   (already-escaped HTML) or a known substitute for them - the shrug's
+   *   never-eat-content rule binds embedder vocabulary too.
+   * Embedder-first: a claim on a name the language defines wins. */
   directive(name: string, attrs: Attrs, renderedChildren: string): string | null;
-  /** Embedder span vocabulary. Same contract as `directive`. */
+  /** Embedder span vocabulary - the inline twin of `directive`
+   * (`[user id=x]Name[/user]` is to `:::user id=x:::` what `[spoiler]` is
+   * to `:::spoiler`). Same contract as `directive`, including the probe:
+   * the live editor asks with "" to decide whether to draw the span whole. */
   span(name: string, attrs: Attrs, renderedChildren: string): string | null;
 }