@cube-drone/marquee-html-renderer 0.7.1 → 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

@@ -2,6 +2,10 @@ import type { Attrs } from "@cube-drone/marquee-parser";
 export interface MediaResolution {
     kind: "image" | "audio" | "video";
     url: string;
+    /** A video that is really a silent animation (a gif that became a video):
+     * drawn looping, muted, autoplaying, with no controls. The embedder decides -
+     * the language only carries the choice. Ignored for images and audio. */
+    loop?: boolean;
 }
 export type TurbolinkLevel = "full" | "title" | "bare";
 /** What an emoji slug becomes: replacement text, or a custom-emoji image. */
@@ -32,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/dist/render.js

@@ -205,7 +205,9 @@ function embed(target, alt, profile) {
             case "audio":
                 return `<audio class="mq-embed" controls src="${url}" aria-label="${escapeAttr(alt)}"></audio>`;
             case "video":
-                return `<video class="mq-embed" controls src="${url}" aria-label="${escapeAttr(alt)}"></video>`;
+                return media.loop === true
+                    ? `<video class="mq-embed" autoplay loop muted playsinline src="${url}" aria-label="${escapeAttr(alt)}"></video>`
+                    : `<video class="mq-embed" controls src="${url}" aria-label="${escapeAttr(alt)}"></video>`;
         }
     }
     // The contractual shrug applied to media: degrade to a labeled link, or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cube-drone/marquee-html-renderer",
-  "version": "0.7.1",
+  "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.1"
+    "@cube-drone/marquee-parser": "^0.8.0"
   },
   "devDependencies": {
-    "@cube-drone/marquee-css": "^0.7.1",
-    "@cube-drone/marquee-fonts": "^0.7.1",
-    "@cube-drone/marquee-turbolink": "^0.7.1",
+    "@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

@@ -8,6 +8,10 @@ import type { Attrs } from "@cube-drone/marquee-parser";
 export interface MediaResolution {
   kind: "image" | "audio" | "video";
   url: string;
+  /** A video that is really a silent animation (a gif that became a video):
+   * drawn looping, muted, autoplaying, with no controls. The embedder decides -
+   * the language only carries the choice. Ignored for images and audio. */
+  loop?: boolean;
 }
 
 export type TurbolinkLevel = "full" | "title" | "bare";
@@ -38,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;
 }
 

package/src/render.ts

@@ -232,7 +232,9 @@ function embed(target: string, alt: string, profile: Profile): string {
       case "audio":
         return `<audio class="mq-embed" controls src="${url}" aria-label="${escapeAttr(alt)}"></audio>`;
       case "video":
-        return `<video class="mq-embed" controls src="${url}" aria-label="${escapeAttr(alt)}"></video>`;
+        return media.loop === true
+          ? `<video class="mq-embed" autoplay loop muted playsinline src="${url}" aria-label="${escapeAttr(alt)}"></video>`
+          : `<video class="mq-embed" controls src="${url}" aria-label="${escapeAttr(alt)}"></video>`;
     }
   }
   // The contractual shrug applied to media: degrade to a labeled link, or