@enmaq/mdgl 0.3.1 → 0.4.0

package/README.md

@@ -81,6 +81,69 @@ Limits: the terminal must be at least as wide and tall as the scene (no resize h
 Library: `play(scene, {write, clock, onWriteError?, onInterrupt?})` returns `{done, stop}` and does no I/O itself;
 `examples/play.mjs` shows the wiring, and `plainFallback(scene)` gives the redirected-output text.
 
+## Browser player (0.4.0)
+
+The browser API reuses the same terminal-cell evaluator. Separate subpath imports
+keep DOM types out of the Node-only entry:
+
+```ts
+import { renderToElement } from '@enmaq/mdgl/dom';
+import '@enmaq/mdgl/mdgl.css';
+const player = renderToElement(document.getElementById('scene')!, source, {
+  maxCells: 12000, maxFps: 30,
+  palette: { accent: '#2563eb' },
+  onError: message => console.warn(message),
+});
+// Viewport owners can call player.pause() / player.play().
+// On unmount: player.destroy(), or stop() to retain the final frame.
+```
+
+`renderToElement(element, source, options?)` replaces the contents with one `<pre>`
+containing adjacent color runs. Invalid scenes/options show literal source plus
+a diagnostic, set `player.error`, and call `onError` if supplied. Source is never
+interpreted as HTML. Replacing a player stops the previous one. `stop()` is
+permanent; `pause()`/`play()` preserve elapsed scene time. `autoplay: false`
+starts paused on the declared fallback; first `play()` starts at time zero.
+Finite scenes finish automatically. RAF uses monotonic elapsed
+time and drops late frames. The scene fps and `maxFps` both apply; defaults are
+30 fps and 12000 cells, with hard ceilings of 60 fps and 12000 cells. Larger
+stages are rejected, not cropped. Existing checker source limits still apply.
+
+Omitting `reducedMotion` follows live `prefers-reduced-motion` changes. `true`
+shows the scene's declared fallback without animation; `false` explicitly
+enables motion. A nonvisual document without RAF also displays the fallback.
+Author `fallback=end` for a meaningful reduced-motion end state.
+
+For a plain page, copy built `dist/browser.mjs` and `mdgl.css` alongside it:
+
+```html
+<link rel="stylesheet" href="./mdgl.css">
+<script type="module" src="./browser.mjs"></script>
+<mdgl-player>
+scene width=24 height=2 fallback=end
+actor greeting = text("Hello") at (1,0) color=accent
+@0: greeting.type(per_char=0.15)
+</mdgl-player>
+```
+
+The browser module exports the API and registers `<mdgl-player>` once. Bundlers
+may instead call `registerMDGLPlayer()` from `@enmaq/mdgl/player`. The element
+accepts inline text or `src="scene.mdgl"` (HTTP(S), normal CORS rules), plus
+`max-cells`, `max-fps`, and `reduced-motion` attributes. Use its `source` property
+for later inline-source updates. Removing the element cancels animation and
+pending fetches; reconnecting reuses its source. `src` takes precedence over
+inline source. Fetch failures show literal diagnostics; superseded responses
+cannot overwrite newer scenes. Inline markup characters must be HTML-escaped
+or assigned through `source`.
+
+The stylesheet provides light/dark defaults for all ten `--mdgl-COLOR` variables
+and `--mdgl-background`. Override them on the host for an application's theme,
+or use the `palette` option for named foreground colors. Evaluator-generated
+fade RGB values remain exact, including terminal black-background blending.
+This is a monospace cell renderer, not WebGL.
+
+`npm run test:dom` runs targeted DOM fixture parity and lifecycle regressions.
+
 ## Development
 
 `npm test` builds, type-checks `test/consumer/consumer.ts` and runs the tests,

package/dist/browser.d.ts

@@ -0,0 +1,3 @@
+export { renderToElement, MDGL_COLORS } from './dom';
+export type { RenderHandle, RenderOptions, MDGLColor } from './dom';
+export { registerMDGLPlayer } from './player';

package/dist/browser.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerMDGLPlayer = exports.MDGL_COLORS = exports.renderToElement = void 0;
+var dom_1 = require("./dom");
+Object.defineProperty(exports, "renderToElement", { enumerable: true, get: function () { return dom_1.renderToElement; } });
+Object.defineProperty(exports, "MDGL_COLORS", { enumerable: true, get: function () { return dom_1.MDGL_COLORS; } });
+var player_1 = require("./player");
+Object.defineProperty(exports, "registerMDGLPlayer", { enumerable: true, get: function () { return player_1.registerMDGLPlayer; } });
+const player_2 = require("./player");
+(0, player_2.registerMDGLPlayer)();