@enmaq/mdgl 0.3.0 → 0.4.0

package/dist/dom.d.ts

@@ -0,0 +1,25 @@
+export declare const MDGL_COLORS: readonly ["normal", "black", "red", "green", "yellow", "blue", "magenta", "cyan", "white", "accent"];
+export type MDGLColor = typeof MDGL_COLORS[number];
+export interface RenderOptions {
+    /** Omit to follow prefers-reduced-motion, including changes while mounted. */
+    reducedMotion?: boolean;
+    /** Reject larger stages; default and hard ceiling: 12000 cells. */
+    maxCells?: number;
+    /** Default 30; hard ceiling 60. The scene's own fps may be lower. */
+    maxFps?: number;
+    palette?: Partial<Record<MDGLColor, string>>;
+    autoplay?: boolean;
+    onError?: (message: string) => void;
+}
+export interface RenderHandle {
+    /** Permanent stop; retain the current frame. */
+    stop(): void;
+    /** Pause/resume without advancing scene time while paused. */
+    pause(): void;
+    play(): void;
+    /** Stop and remove this player's output. Safe after replacement. */
+    destroy(): void;
+    readonly error: string | null;
+}
+/** Browser-only entry point. Importing this module itself is safe outside a browser. */
+export declare function renderToElement(el: HTMLElement, source: string, opts?: RenderOptions): RenderHandle;

package/dist/dom.js

@@ -0,0 +1,206 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MDGL_COLORS = void 0;
+exports.renderToElement = renderToElement;
+const eval_1 = require("./eval");
+exports.MDGL_COLORS = ['normal', 'black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white', 'accent'];
+const owners = new WeakMap();
+function color(value, background = false) {
+    if (/^#[0-9a-f]{6}$/i.test(value))
+        return value;
+    if (exports.MDGL_COLORS.includes(value))
+        return `var(--mdgl-${value})`;
+    return background ? 'transparent' : 'var(--mdgl-normal)';
+}
+/** Paint evaluator cells verbatim, grouping only adjacent equal colors. Never parse HTML. */
+function paint(pre, frame) {
+    const doc = pre.ownerDocument;
+    const fragment = doc.createDocumentFragment();
+    frame.cells.forEach((row, y) => {
+        let x = 0;
+        while (x < row.length) {
+            const first = row[x];
+            let text = first.r;
+            let end = x + 1;
+            while (end < row.length && row[end].fg === first.fg && row[end].bg === first.bg)
+                text += row[end++].r;
+            const span = doc.createElement('span');
+            span.textContent = text;
+            span.dataset.mdglFg = first.fg;
+            span.dataset.mdglBg = first.bg;
+            span.style.color = color(first.fg);
+            span.style.backgroundColor = color(first.bg, true);
+            fragment.appendChild(span);
+            x = end;
+        }
+        if (y + 1 < frame.height)
+            fragment.appendChild(doc.createTextNode('\n'));
+    });
+    pre.replaceChildren(fragment);
+}
+function cap(value, fallback, ceiling, name) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isFinite(value) || value < 1)
+        throw new Error(`${name} must be a finite number >= 1`);
+    return Math.min(Math.floor(value), ceiling);
+}
+/** Browser-only entry point. Importing this module itself is safe outside a browser. */
+function renderToElement(el, source, opts = {}) {
+    owners.get(el)?.stop();
+    const doc = el.ownerDocument;
+    const win = doc.defaultView;
+    const pre = doc.createElement('pre');
+    pre.className = 'mdgl-frame';
+    pre.setAttribute('aria-live', 'off');
+    el.replaceChildren(pre);
+    let error = null;
+    let stopped = false, paused = opts.autoplay === false, finished = false, started = false;
+    let request = null;
+    let media;
+    let reduced = opts.reducedMotion === true;
+    let elapsed = 0, origin = 0, lastPaint = -Infinity;
+    let resume = () => { };
+    let mediaChange = () => { };
+    const now = () => win?.performance.now() ?? 0;
+    const cancel = () => {
+        if (request !== null)
+            win?.cancelAnimationFrame(request);
+        request = null;
+    };
+    const stop = () => {
+        stopped = true;
+        cancel();
+        media?.removeEventListener('change', mediaChange);
+        if (owners.get(el) === handle)
+            owners.delete(el);
+    };
+    const handle = {
+        stop,
+        pause() {
+            if (stopped || paused)
+                return;
+            if (!reduced && !finished)
+                elapsed = Math.max(elapsed, now() - origin);
+            paused = true;
+            cancel();
+        },
+        play() {
+            if (stopped || !paused)
+                return;
+            paused = false;
+            try {
+                resume();
+            }
+            catch (e) {
+                fail(e instanceof Error ? e.message : String(e));
+            }
+        },
+        destroy() { stop(); pre.remove(); },
+        get error() { return error; },
+    };
+    owners.set(el, handle);
+    const fail = (message) => {
+        error = message;
+        stop();
+        pre.classList.add('mdgl-error');
+        pre.textContent = `${source}\n\nMDGL: ${message}`;
+        // Consumer error reporting must not turn a rejected scene into a page exception.
+        try {
+            opts.onError?.(message);
+        }
+        catch { /* callback belongs to the host */ }
+    };
+    try {
+        const maxCells = cap(opts.maxCells, 12000, 12000, 'maxCells');
+        const maxFps = cap(opts.maxFps, 30, 60, 'maxFps');
+        const result = (0, eval_1.compile)(source);
+        if (!result.ok) {
+            fail(result.diagnostics.map(d => `${d.line}:${d.col}: ${d.message}`).join('\n'));
+            return handle;
+        }
+        const scene = result.scene;
+        if (scene.width * scene.height > maxCells) {
+            fail(`stage has ${scene.width * scene.height} cells; maxCells is ${maxCells}`);
+            return handle;
+        }
+        for (const name of exports.MDGL_COLORS) {
+            const value = opts.palette?.[name];
+            if (value !== undefined)
+                pre.style.setProperty(`--mdgl-${name}`, value);
+        }
+        if (opts.reducedMotion === undefined && win?.matchMedia) {
+            media = win.matchMedia('(prefers-reduced-motion: reduce)');
+            reduced = media.matches;
+        }
+        // A headless/nonvisual document has no animation clock: render the declared fallback.
+        reduced || (reduced = !win?.requestAnimationFrame);
+        const interval = 1000 / Math.min(scene.fps, maxFps);
+        const draw = (time) => {
+            const frame = (0, eval_1.frameNs)(scene, Math.min(Number.MAX_SAFE_INTEGER, Math.floor(time * 1e6)));
+            paint(pre, frame);
+            finished = frame.done === true;
+            lastPaint = time;
+            started = true;
+        };
+        const tick = () => {
+            request = null;
+            if (stopped || paused || reduced || finished)
+                return;
+            try {
+                elapsed = Math.max(elapsed, now() - origin);
+                if (elapsed - lastPaint + 1e-7 >= interval)
+                    draw(elapsed);
+                if (!finished)
+                    request = win.requestAnimationFrame(tick);
+            }
+            catch (e) {
+                fail(e instanceof Error ? e.message : String(e));
+            }
+        };
+        resume = () => {
+            if (stopped || reduced || paused || finished)
+                return;
+            if (!started)
+                draw(elapsed);
+            if (finished)
+                return;
+            origin = now() - elapsed;
+            if (request === null)
+                request = win.requestAnimationFrame(tick);
+        };
+        mediaChange = () => {
+            if (stopped)
+                return;
+            try {
+                const next = media.matches;
+                if (next === reduced)
+                    return;
+                if (!paused && !finished && !reduced)
+                    elapsed = Math.max(elapsed, now() - origin);
+                reduced = next;
+                cancel();
+                if (reduced)
+                    paint(pre, (0, eval_1.fallbackFrame)(scene));
+                else if (started || !paused) {
+                    draw(elapsed);
+                    resume();
+                }
+            }
+            catch (e) {
+                fail(e instanceof Error ? e.message : String(e));
+            }
+        };
+        media?.addEventListener('change', mediaChange);
+        if (reduced || paused)
+            paint(pre, (0, eval_1.fallbackFrame)(scene));
+        else {
+            draw(0);
+            resume();
+        }
+    }
+    catch (e) {
+        fail(e instanceof Error ? e.message : String(e));
+    }
+    return handle;
+}

package/dist/eval.js

@@ -274,8 +274,10 @@ class Grid {
         if (col < 0 || row < 0 || col >= this.w || row >= this.h || r === ' ' || alpha <= 0)
             return;
         const c = this.cells[row][col];
+        // source-over onto the cell's current colour: the glyph already there if any, else the (black) background
+        const dest = c.r !== ' ' ? c.fg : c.bg;
         c.r = r;
-        c.fg = alpha >= 1 ? color : blend(color, alpha, c.bg);
+        c.fg = alpha >= 1 ? color : blend(color, alpha, dest);
     }
 }
 const q9 = (v) => Math.round(v * 1e9) / 1e9;

package/dist/index.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.RESET = exports.SHOW_CURSOR = exports.HIDE_CURSOR = exports.SYNC_END = exports.SYNC_BEGIN = exports.sanitizeRune = exports.plainText = exports.plainFallback = exports.play = exports.MAX_REQUEST_LINE = exports.mathInt = exports.handleLine = exports.fallbackFrame = exports.frameNs = exports.compileDocument = exports.compile = exports.graphemes = exports.graphemeRanges = exports.graphemeCount = exports.clusterWidth = exports.cellRune = exports.UNICODE_VERSION = exports.parse = exports.parseChecked = exports.checkDocument = exports.check = exports.VERSION = void 0;
 // @enmaq/mdgl: MDGL 0.1 parser and checker (development tree; evaluator and
 // rendering are not implemented yet). Spec: ../SPEC.md
-exports.VERSION = '0.3.0';
+exports.VERSION = '0.4.0';
 var check_1 = require("./check");
 Object.defineProperty(exports, "check", { enumerable: true, get: function () { return check_1.check; } });
 Object.defineProperty(exports, "checkDocument", { enumerable: true, get: function () { return check_1.checkDocument; } });

package/dist/parse.js

@@ -6,9 +6,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.bytes = exports.MAX_LINE = exports.MAX_INPUT = void 0;
 exports.decimalToNs = decimalToNs;
 exports.parse = parse;
+const utf8 = new TextEncoder();
 exports.MAX_INPUT = 256 * 1024;
 exports.MAX_LINE = 16384;
-const bytes = (s) => Buffer.byteLength(s, 'utf8');
+const bytes = (s) => utf8.encode(s).length;
 exports.bytes = bytes;
 class SyntaxErr {
     constructor(d) {

package/dist/player.d.ts

@@ -0,0 +1,2 @@
+/** Register once, explicitly, without reading browser globals at module import time. */
+export declare function registerMDGLPlayer(): void;

package/dist/player.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerMDGLPlayer = registerMDGLPlayer;
+const dom_1 = require("./dom");
+/** Register once, explicitly, without reading browser globals at module import time. */
+function registerMDGLPlayer() {
+    if (typeof customElements === 'undefined' || typeof HTMLElement === 'undefined')
+        return;
+    if (customElements.get('mdgl-player'))
+        return;
+    class MDGLPlayer extends HTMLElement {
+        constructor() {
+            super(...arguments);
+            this.revision = 0;
+            this.queued = false;
+        }
+        static get observedAttributes() { return ['src', 'reduced-motion', 'max-cells', 'max-fps']; }
+        /** Use this property for programmatic inline-source updates after connection. */
+        get source() { return this.inline ?? this.textContent ?? ''; }
+        set source(value) { this.inline = value; this.schedule(); }
+        connectedCallback() { this.schedule(); }
+        disconnectedCallback() {
+            this.revision++;
+            this.pending?.abort();
+            this.playback?.stop();
+        }
+        attributeChangedCallback() { this.schedule(); }
+        schedule() {
+            this.revision++;
+            this.pending?.abort();
+            this.playback?.stop();
+            if (this.queued)
+                return;
+            this.queued = true;
+            queueMicrotask(() => {
+                this.queued = false;
+                if (this.isConnected)
+                    void this.load();
+            });
+        }
+        async load() {
+            if (this.inline === undefined)
+                this.inline = this.textContent ?? '';
+            const revision = this.revision;
+            const src = this.getAttribute('src');
+            let source = this.inline;
+            try {
+                if (src !== null) {
+                    const url = new URL(src, this.ownerDocument.baseURI);
+                    if (url.protocol !== 'https:' && url.protocol !== 'http:')
+                        throw new Error('src must use HTTP or HTTPS');
+                    this.pending = new AbortController();
+                    const response = await fetch(url.href, { signal: this.pending.signal });
+                    if (!response.ok)
+                        throw new Error(`src request failed (${response.status})`);
+                    source = await response.text();
+                }
+                if (revision !== this.revision || !this.isConnected)
+                    return;
+                this.playback = (0, dom_1.renderToElement)(this, source, {
+                    reducedMotion: this.hasAttribute('reduced-motion') ? this.getAttribute('reduced-motion') !== 'false' : undefined,
+                    maxCells: this.hasAttribute('max-cells') ? Number(this.getAttribute('max-cells')) : undefined,
+                    maxFps: this.hasAttribute('max-fps') ? Number(this.getAttribute('max-fps')) : undefined,
+                });
+            }
+            catch (e) {
+                if (revision !== this.revision || !this.isConnected)
+                    return;
+                const pre = this.ownerDocument.createElement('pre');
+                pre.className = 'mdgl-frame mdgl-error';
+                pre.textContent = `${this.inline}\n\nMDGL: ${e instanceof Error ? e.message : String(e)}`;
+                this.replaceChildren(pre);
+            }
+        }
+    }
+    customElements.define('mdgl-player', MDGLPlayer);
+}

package/mdgl.css

@@ -0,0 +1,52 @@
+/* Variables inherit from the host; set them on mdgl-player or a wrapper to theme. */
+:root {
+  --mdgl-normal: #172033;
+  --mdgl-black: #000000;
+  --mdgl-red: #b42318;
+  --mdgl-green: #16713c;
+  --mdgl-yellow: #8b6100;
+  --mdgl-blue: #2459bd;
+  --mdgl-magenta: #9126a7;
+  --mdgl-cyan: #00788b;
+  --mdgl-white: #435069;
+  --mdgl-accent: #005fcc;
+  --mdgl-background: #f6f8fc;
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --mdgl-normal: #e6edf7;
+    --mdgl-black: #000000;
+    --mdgl-red: #ff7b72;
+    --mdgl-green: #7ee787;
+    --mdgl-yellow: #f2cc60;
+    --mdgl-blue: #79a9ff;
+    --mdgl-magenta: #e2a8ff;
+    --mdgl-cyan: #76e3ea;
+    --mdgl-white: #ffffff;
+    --mdgl-accent: #a5c8ff;
+    --mdgl-background: #111827;
+  }
+}
+mdgl-player { display: block; }
+.mdgl-frame {
+  display: block;
+  margin: 0;
+  padding: 0.75rem;
+  overflow: auto;
+  max-width: 100%;
+  box-sizing: border-box;
+  white-space: pre;
+  direction: ltr;
+  unicode-bidi: isolate;
+  font-family: ui-monospace, SFMono-Regular, Consolas, 'Liberation Mono', monospace;
+  font-size: 14px;
+  font-weight: normal;
+  font-style: normal;
+  font-variant-ligatures: none;
+  letter-spacing: 0;
+  line-height: 1.2;
+  color: var(--mdgl-normal);
+  background: var(--mdgl-background);
+}
+.mdgl-frame > span { font: inherit; letter-spacing: inherit; }
+.mdgl-error { white-space: pre-wrap; overflow-wrap: anywhere; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enmaq/mdgl",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "MDGL 0.1 parser, checker, evaluator, terminal-cell renderer and terminal player.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,7 +9,20 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./dom": {
+      "types": "./dist/dom.d.ts",
+      "default": "./dist/dom.js"
+    },
+    "./player": {
+      "types": "./dist/player.d.ts",
+      "default": "./dist/player.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "default": "./dist/browser.mjs"
+    },
+    "./mdgl.css": "./mdgl.css"
   },
   "publishConfig": {
     "access": "public"
@@ -20,15 +33,17 @@
     "README.md",
     "LICENSE-MIT",
     "LICENSE-APACHE",
-    "UNICODE-LICENSE.txt"
+    "UNICODE-LICENSE.txt",
+    "mdgl.css"
   ],
   "scripts": {
-    "build": "tsc -p .",
+    "build": "tsc -p . && esbuild src/browser.ts --bundle --format=esm --target=es2020 --outfile=dist/browser.mjs",
     "prepack": "npm run build",
     "test:types": "tsc -p test/consumer",
     "test": "npm run build && npm run test:types && node --test test/*.test.js",
     "example:js": "npm run build && node examples/render.mjs",
-    "example:ts": "npm run build && tsc -p examples && node .examples/render.js"
+    "example:ts": "npm run build && tsc -p examples && node .examples/render.js",
+    "test:dom": "npm run build && node --test test/dom.test.js"
   },
   "repository": {
     "type": "git",
@@ -48,7 +63,9 @@
   ],
   "license": "MIT OR Apache-2.0",
   "devDependencies": {
-    "typescript": "5.9.3"
+    "typescript": "5.9.3",
+    "esbuild": "0.24.2",
+    "jsdom": "22.1.0"
   },
   "bin": {
     "mdgl": "bin/mdgl.js",