scenic-prism-standalone 0.1.0

package/dist/component.js

@@ -0,0 +1,313 @@
+import { shaderConstant } from "./embed.js";
+import { minify } from "./minify.js";
+import { configureCanvas } from "./options.js";
+/** The file's own header: what it is, and what it is not. */
+function header(config) {
+    return `/**
+ * <${config.name} /> — one scenic-prism scene, compiled, with nothing to install.
+ *
+ * Generated by scenic-prism-standalone. The scene is already WGSL by the time
+ * this file exists: every shape, material and light of it is baked into the
+ * TRACE source below as numeric literals, so there is no library to add to
+ * the project this is pasted into and nothing is fetched at runtime. The only
+ * import is React; the only requirement is a browser with WebGPU, and a
+ * TypeScript whose DOM library declares it (6.0 and later do).
+ *
+ *   <${config.name} size={720} className="rounded-lg" />
+ *
+ * The component renders a bare <canvas> and nothing else — no wrapper, no
+ * styling, no fallback element — so its size on the page, and what it sits in,
+ * stay yours. Everything a <canvas> takes is passed straight through.
+ *
+ * Nothing regenerates this file. Edit it as your own.
+ */`;
+}
+/** The scene, the framing and the budget, as the constants the component reads. */
+function constants(config) {
+    return [
+        '/** Backing resolution the component falls back to, in pixels. */',
+        `const WIDTH = ${config.width};`,
+        `const HEIGHT = ${config.height};`,
+        '',
+        '/** Samples per pixel accumulated before the loop stops. */',
+        `const MAX_FRAMES = ${config.maxFrames};`,
+        '',
+        '/** A fixed base seed, or null for a fresh sample sequence on every mount. */',
+        `const SEED: number | null = ${config.seed === null ? 'null' : config.seed};`,
+        '',
+        '/** The WebGPU flags this file uses, by value. */',
+        'const BUFFER_STORAGE = 0x80;',
+        'const BUFFER_UNIFORM = 0x40;',
+        'const BUFFER_COPY_DST = 0x08;',
+        '',
+        '// The scene itself: every shape, material and light of it, compiled to a',
+        '// WGSL compute shader with all of its parameters baked in as literals. One',
+        "// invocation per pixel adds one sample to that pixel's running sum.",
+        shaderConstant('TRACE', config.trace),
+        '',
+        '// Tonemap and gamma, from the accumulation buffer to the canvas.',
+        shaderConstant('DISPLAY', config.display),
+    ].join('\n');
+}
+/** The props, which are a canvas's plus the render's own. */
+function props(name) {
+    return `/**
+ * Everything a <canvas> takes, minus the five this component owns. \`width\` and
+ * \`height\` are the backing store rather than the CSS box, and \`onProgress\` and
+ * \`onError\` are DOM media events on every element — here they mean the render's
+ * progress and the render's failure.
+ */
+type CanvasProps = Omit<
+  ComponentPropsWithoutRef<'canvas'>,
+  'width' | 'height' | 'onProgress' | 'onError' | 'children'
+>;
+
+export interface ${name}Props extends CanvasProps {
+  /** Square backing resolution in pixels; \`width\`/\`height\` override it. */
+  size?: number;
+  /** Backing-store width in pixels. Not a CSS width. */
+  width?: number;
+  /** Backing-store height in pixels. Not a CSS height. */
+  height?: number;
+  /** Stop accumulating after this many samples per pixel. */
+  maxFrames?: number;
+  /** Fix the sample sequence, for a reproducible accumulation. */
+  seed?: number | null;
+  /** Called after every accumulated frame, with the running sample count. */
+  onProgress?: (frames: number, total: number) => void;
+  /** Called once the accumulation finishes, with the count. */
+  onDone?: (frames: number) => void;
+  /** Called when the scene cannot be traced at all — no WebGPU, say. */
+  onError?: (error: Error) => void;
+}`;
+}
+/**
+ * The fixed half of the file: the same progressive path tracer the library
+ * runs, inside the effect that owns it.
+ */
+function body(config) {
+    const { name, workgroup } = config;
+    return `export function ${name}({
+  size,
+  width,
+  height,
+  maxFrames = MAX_FRAMES,
+  seed = SEED,
+  onProgress,
+  onDone,
+  onError,
+  ...canvasProps
+}: ${name}Props) {
+  const canvasRef = useRef<HTMLCanvasElement | null>(null);
+
+  /**
+   * The callbacks are read through a ref, so passing them inline — which is how
+   * anyone writes them — does not count as a change of scene. A fresh
+   * onProgress on every parent render would otherwise tear the render down and
+   * start the accumulation again from noise.
+   */
+  const callbacks = useRef({ onProgress, onDone, onError });
+  useEffect(() => {
+    callbacks.current = { onProgress, onDone, onError };
+  });
+
+  // The backing store, which is what the trace is sized for. How large the
+  // canvas is drawn is CSS, and so the caller's.
+  const w = Math.max(1, Math.round(width ?? size ?? WIDTH));
+  const h = Math.max(1, Math.round(height ?? size ?? HEIGHT));
+
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+
+    let running = true;
+    let raf = 0;
+    let device: GPUDevice | undefined;
+
+    /**
+     * A callback is the caller's code, so a throw inside one must not take the
+     * loop down with it. Report it the way the browser reports a throwing event
+     * listener: asynchronously, leaving everything here untouched.
+     */
+    const notify = (report: () => void) => {
+      try {
+        report();
+      } catch (error) {
+        setTimeout(() => {
+          throw error;
+        });
+      }
+    };
+
+    const start = async () => {
+      const gpu = navigator.gpu as GPU | undefined;
+      const adapter = await gpu?.requestAdapter();
+      if (!gpu || !adapter) throw new Error('This scene needs a browser with WebGPU.');
+      // The accumulation buffer is 16 bytes a pixel, so the storage limits are
+      // raised to whatever the adapter allows: a large canvas outgrows them.
+      device = await adapter.requestDevice({
+        requiredLimits: {
+          maxStorageBufferBindingSize: adapter.limits.maxStorageBufferBindingSize,
+          maxBufferSize: adapter.limits.maxBufferSize,
+        },
+      });
+      // Unmounted while the device was on its way: give it straight back.
+      if (!running) {
+        device.destroy();
+        return;
+      }
+
+      const context = canvas.getContext('webgpu') as GPUCanvasContext | null;
+      if (!context) throw new Error('This canvas cannot provide a WebGPU context.');
+      const format = gpu.getPreferredCanvasFormat();
+${configureCanvas(config.colorSpace, config.alpha, '      ')}
+      // A shader that will not build is reported through onError, in the
+      // compiler's own words, rather than printed to a console.
+      device.pushErrorScope('validation');
+      const traceModule = device.createShaderModule({ code: TRACE });
+      const displayModule = device.createShaderModule({ code: DISPLAY });
+      const invalid = await device.popErrorScope();
+      if (invalid) throw new Error(invalid.message);
+
+      const trace = await device.createComputePipelineAsync({
+        layout: 'auto',
+        compute: { module: traceModule, entryPoint: 'main' },
+      });
+      const display = await device.createRenderPipelineAsync({
+        layout: 'auto',
+        vertex: { module: displayModule, entryPoint: 'vertexMain' },
+        fragment: { module: displayModule, entryPoint: 'fragmentMain', targets: [{ format }] },
+      });
+      if (!running) return;
+
+      // One RGBA32F running sum per pixel, zeroed at creation: read and written
+      // in place by the trace, read by the display.
+      const accum = device.createBuffer({ size: w * h * 16, usage: BUFFER_STORAGE });
+      // Per sample: the resolution, which sample this is, and its seed.
+      const frameBuffer = device.createBuffer({
+        size: 16,
+        usage: BUFFER_UNIFORM | BUFFER_COPY_DST,
+      });
+      // For the display: the resolution, and how many samples have gone in.
+      const displayBuffer = device.createBuffer({
+        size: 16,
+        usage: BUFFER_UNIFORM | BUFFER_COPY_DST,
+      });
+
+      const frameData = new ArrayBuffer(16);
+      new Float32Array(frameData, 0, 2).set([w, h]);
+      const frameWords = new Uint32Array(frameData, 8, 2);
+      const displayData = new Float32Array([w, h, 0, 0]);
+
+      const gpuDevice = device;
+      const bind = (pipeline: GPUComputePipeline | GPURenderPipeline, uniforms: GPUBuffer) =>
+        gpuDevice.createBindGroup({
+          layout: pipeline.getBindGroupLayout(0),
+          entries: [
+            { binding: 0, resource: { buffer: uniforms } },
+            { binding: 1, resource: { buffer: accum } },
+          ],
+        });
+      const traceGroup = bind(trace, frameBuffer);
+      const displayGroup = bind(display, displayBuffer);
+
+      let frame = 0;
+
+      const draw = () => {
+        if (!running) return;
+        frameWords[0] = frame;
+        frameWords[1] =
+          seed === null
+            ? (Math.random() * 4294967296) >>> 0
+            : (Math.imul(seed + frame, 2654435761) ^ frame) >>> 0;
+        gpuDevice.queue.writeBuffer(frameBuffer, 0, frameData);
+        displayData[2] = frame + 1;
+        gpuDevice.queue.writeBuffer(displayBuffer, 0, displayData);
+
+        const encoder = gpuDevice.createCommandEncoder();
+
+        // Trace: one invocation per pixel adds one new sample to its running sum.
+        const pass = encoder.beginComputePass();
+        pass.setPipeline(trace);
+        pass.setBindGroup(0, traceGroup);
+        pass.dispatchWorkgroups(Math.ceil(w / ${workgroup[0]}), Math.ceil(h / ${workgroup[1]}));
+        pass.end();
+
+        // Display: tonemap what has accumulated so far onto the canvas.
+        const out = encoder.beginRenderPass({
+          colorAttachments: [
+            {
+              view: context.getCurrentTexture().createView(),
+              loadOp: 'clear',
+              storeOp: 'store',
+              clearValue: [0, 0, 0, 0],
+            },
+          ],
+        });
+        out.setPipeline(display);
+        out.setBindGroup(0, displayGroup);
+        out.draw(3);
+        out.end();
+
+        gpuDevice.queue.submit([encoder.finish()]);
+        frame++;
+        notify(() => callbacks.current.onProgress?.(frame, maxFrames));
+
+        if (frame >= maxFrames) {
+          notify(() => callbacks.current.onDone?.(frame));
+          return;
+        }
+        // The next sample waits for this one, so a scene slower than the
+        // screen never queues work faster than the GPU can drain it.
+        void gpuDevice.queue.onSubmittedWorkDone().then(() => {
+          if (running) raf = requestAnimationFrame(draw);
+        });
+      };
+
+      draw();
+    };
+
+    start().catch((cause: unknown) => {
+      // A scene that cannot be traced is the caller's to present: there is no
+      // fallback element here, because anything drawn in place of the canvas
+      // would be this component's styling rather than theirs.
+      if (!running) return;
+      notify(() =>
+        callbacks.current.onError?.(cause instanceof Error ? cause : new Error(String(cause))),
+      );
+    });
+
+    // Unmounting, or a change of size, gives the GPU back: the device goes, and
+    // every buffer and pipeline on it with it.
+    return () => {
+      running = false;
+      cancelAnimationFrame(raf);
+      device?.destroy();
+    };
+  }, [h, maxFrames, seed, w]);
+
+  return <canvas ref={canvasRef} width={w} height={h} {...canvasProps} />;
+}`;
+}
+/**
+ * The whole `.tsx` file for one scene: the baked constants, the props, then the
+ * component that reads them. `min` squeezes the two shaders — which are most of
+ * the file — and leaves the component alone, since that half is meant to be
+ * read, and whatever bundles it will minify it anyway.
+ */
+export function componentSource(config, min = false) {
+    const shaders = min
+        ? { ...config, trace: minify(config.trace), display: minify(config.display) }
+        : config;
+    const imports = [
+        "import { useEffect, useRef } from 'react';",
+        "import type { ComponentPropsWithoutRef } from 'react';",
+    ].join('\n');
+    const parts = [header(config), imports, constants(shaders), props(config.name), body(config)];
+    // A directive has to be the very first thing in the file, above the header.
+    if (config.useClient)
+        parts.unshift("'use client';");
+    if (config.exportDefault)
+        parts.push(`export default ${config.name};`);
+    return `${parts.join('\n\n')}\n`;
+}

package/dist/download.d.ts

@@ -0,0 +1,24 @@
+import type { StandaloneOptions } from './html.js';
+import type { FluentSceneSpec } from 'scenic-prism-fluent';
+/** What a downloaded file is called when the caller does not name it. */
+export declare const DEFAULT_FILENAME = "scene.html";
+export interface DownloadOptions extends StandaloneOptions {
+    /** The name to save under. `.html` is appended if it is missing. */
+    filename?: string;
+}
+/**
+ * Build the page for `spec` and save it, as though the visitor had clicked a
+ * link to it. Returns the same HTML {@link buildStandaloneHtml} would, so a
+ * caller that also wants to show or measure what it just saved need not build
+ * it twice.
+ *
+ * ```ts
+ * <button onClick={() => downloadStandaloneHtml(spec, { size: 900, min: true })}>
+ *   Download
+ * </button>
+ * ```
+ *
+ * Browser only, and deliberately not guarded: called where there is no
+ * `document` it throws, rather than quietly doing nothing on a server render.
+ */
+export declare function downloadStandaloneHtml(spec: FluentSceneSpec, options?: DownloadOptions): string;

package/dist/download.js

@@ -0,0 +1,46 @@
+/**
+ * Handing the file to the person looking at the page.
+ *
+ * The rest of this package is a pure function of a scene and runs anywhere —
+ * Node, a build script, a worker. This one is the browser half: it is what
+ * turns "generate a page" into "download a page", which is the thing an app
+ * with an export button actually wants and the only part that needs a DOM.
+ */
+import { buildStandaloneHtml } from "./html.js";
+/** What a downloaded file is called when the caller does not name it. */
+export const DEFAULT_FILENAME = 'scene.html';
+/** `name.html` for anything that does not already end in `.html` or `.htm`. */
+function withExtension(filename) {
+    return /\.html?$/i.test(filename) ? filename : `${filename}.html`;
+}
+/**
+ * Build the page for `spec` and save it, as though the visitor had clicked a
+ * link to it. Returns the same HTML {@link buildStandaloneHtml} would, so a
+ * caller that also wants to show or measure what it just saved need not build
+ * it twice.
+ *
+ * ```ts
+ * <button onClick={() => downloadStandaloneHtml(spec, { size: 900, min: true })}>
+ *   Download
+ * </button>
+ * ```
+ *
+ * Browser only, and deliberately not guarded: called where there is no
+ * `document` it throws, rather than quietly doing nothing on a server render.
+ */
+export function downloadStandaloneHtml(spec, options = {}) {
+    const html = buildStandaloneHtml(spec, options);
+    const url = URL.createObjectURL(new Blob([html], { type: 'text/html;charset=utf-8' }));
+    const link = document.createElement('a');
+    link.href = url;
+    link.download = withExtension(options.filename ?? DEFAULT_FILENAME);
+    // Firefox only follows a click on an element that is in the document.
+    link.style.display = 'none';
+    document.body.append(link);
+    link.click();
+    link.remove();
+    // The download reads the blob asynchronously, so the URL has to outlive the
+    // click — a tick is enough, and holding it longer would leak the whole file.
+    setTimeout(() => URL.revokeObjectURL(url));
+    return html;
+}

package/dist/embed.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The one check every generated file shares.
+ *
+ * Both of the files this package writes — a page and a component — carry the
+ * two shaders as template literals, so both need the same promise kept: that
+ * nothing in a shader ends the literal, or the element around it, early.
+ *
+ * It is a guard on a promise rather than a case to handle. `compile.ts` emits
+ * WGSL out of numbers and fixed text, and the one part of a shader it does not
+ * write — a `custom` node's own source — is checked for exactly this list by
+ * the builder that takes it. So this fails loudly rather than writing a broken
+ * file.
+ */
+/** Throw unless `source` can be embedded verbatim as a template literal. */
+export declare function checkEmbeddable(name: string, source: string): void;
+/**
+ * `const NAME = ` + the shader, as one line and its contents. The opening
+ * backtick is followed by the shader and nothing else, which WGSL does not
+ * insist on the way GLSL's first-line `#version` did, but which keeps a
+ * shader's line numbers in an error message the line numbers of the string.
+ */
+export declare function shaderConstant(name: string, source: string): string;

package/dist/embed.js

@@ -0,0 +1,40 @@
+/**
+ * The one check every generated file shares.
+ *
+ * Both of the files this package writes — a page and a component — carry the
+ * two shaders as template literals, so both need the same promise kept: that
+ * nothing in a shader ends the literal, or the element around it, early.
+ *
+ * It is a guard on a promise rather than a case to handle. `compile.ts` emits
+ * WGSL out of numbers and fixed text, and the one part of a shader it does not
+ * write — a `custom` node's own source — is checked for exactly this list by
+ * the builder that takes it. So this fails loudly rather than writing a broken
+ * file.
+ */
+/**
+ * What a shader may never contain: something a template literal reads as an
+ * escape or as an interpolation, or that closes the `<script>` a page puts one
+ * in. The last two matter to the HTML file alone, but a shader that could not
+ * go in a page is not one worth putting in a component either — the two files
+ * are the same scene, and an author should not find out which is which.
+ */
+const FORBIDDEN = ['`', '${', '\\', '</script', '<!--'];
+/** Throw unless `source` can be embedded verbatim as a template literal. */
+export function checkEmbeddable(name, source) {
+    for (const forbidden of FORBIDDEN) {
+        if (source.includes(forbidden)) {
+            throw new Error(`scenic-prism-standalone: the ${name} shader contains '${forbidden}', ` +
+                'which cannot be embedded in a generated file as a template literal.');
+        }
+    }
+}
+/**
+ * `const NAME = ` + the shader, as one line and its contents. The opening
+ * backtick is followed by the shader and nothing else, which WGSL does not
+ * insist on the way GLSL's first-line `#version` did, but which keeps a
+ * shader's line numbers in an error message the line numbers of the string.
+ */
+export function shaderConstant(name, source) {
+    checkEmbeddable(name, source);
+    return `const ${name} = \`${source}\`;`;
+}

package/dist/highlight.d.ts

@@ -0,0 +1,100 @@
+/**
+ * A page's source, coloured — for showing or handing out the markup
+ * {@link buildStandaloneHtml} wrote rather than the scene it draws.
+ *
+ * This package may not depend on the site (see `CLAUDE.md`), so it cannot
+ * reach for the site's highlighters. What follows is its own tokenizing: a
+ * small WGSL grammar for the shaders baked into the script, and a tokenizer over
+ * that script, the stylesheet and the markup around them. Like its site
+ * counterparts it is narrow on purpose — it assumes the input is a page this
+ * package generated (every template literal in the script is a shader), not
+ * arbitrary hand-written HTML.
+ */
+export interface FragmentOptions {
+    /**
+     * Bake in the site's dark palette instead of its light one. Default false —
+     * the colours are fixed values rather than custom properties, so this is
+     * the one choice about them the caller gets.
+     */
+    dark?: boolean;
+    /**
+     * Put this in front of every class name, both in the markup and in the
+     * stylesheet. Default `''`, which is the single letters
+     * {@link highlightStandaloneHtml} uses; give a prefix (`'sd-'`, say) where
+     * the host page might already have styled `.b` or `.l` itself.
+     */
+    prefix?: string;
+}
+export interface HighlightOptions extends FragmentOptions {
+    /** The document's title. Default `scenic-prism source`. */
+    title?: string;
+    /**
+     * Let the long lines wrap instead of scrolling sideways. Default false: the
+     * source sits in a `<pre>` and a line as long as a minified page's is
+     * reached by scrolling. True drops the `<pre>` for a `<div>` set to
+     * `white-space: pre-wrap`, so the same source folds to the window's width —
+     * the indentation is still the file's, but a line break on screen may not
+     * be one in the file.
+     */
+    wrap?: boolean;
+}
+/** The two halves of a highlighted page, for a caller assembling their own. */
+export interface HighlightedFragment {
+    /**
+     * The coloured source as markup — nothing but text and `<span>`s, with no
+     * `<pre>`, `<code>` or wrapper of any kind around it. It carries the
+     * original's own newlines and indentation, so whatever encloses it has to
+     * preserve them (a `<pre>`, or `white-space: pre` — `pre-wrap` where the
+     * long lines should fold rather than scroll).
+     */
+    code: string;
+    /**
+     * The rules those spans need, as stylesheet text: one rule per token class
+     * and nothing else — no `:root`, no `body`, no rule for the container.
+     */
+    css: string;
+}
+/**
+ * The same colouring as {@link highlightStandaloneHtml}, handed back in two
+ * pieces instead of as a document: the marked-up source, and the stylesheet
+ * that gives it its colours. Neither carries a `<pre>`, a `<code>`, a `<style>`
+ * or anything else around it, so both can be dropped into a page of the
+ * caller's own — a docs template, a React component, an email — beside
+ * whatever else it shows.
+ *
+ * ```ts
+ * import { buildStandaloneHtml, highlightStandaloneHtmlFragment } from 'scenic-prism-standalone';
+ *
+ * const html = buildStandaloneHtml(spec);
+ * const { code, css } = highlightStandaloneHtmlFragment(html, { prefix: 'sd-' });
+ *
+ * page = `<style>${css}</style><pre class="listing"><code>${code}</code></pre>`;
+ * ```
+ *
+ * The markup is the original's text with the characters that would not survive
+ * it escaped, so the container must preserve whitespace: `code` holds the
+ * newlines and the indentation, and the stylesheet says nothing about them.
+ */
+export declare function highlightStandaloneHtmlFragment(html: string, options?: FragmentOptions): HighlightedFragment;
+/**
+ * Render a page {@link buildStandaloneHtml} wrote as coloured source, rather
+ * than as the scene it draws — a self-contained document with no dependency
+ * of its own, ready to be written to disk, pasted somewhere that keeps
+ * formatting, or shown alongside the render it came from.
+ *
+ * ```ts
+ * import { buildStandaloneHtml, highlightStandaloneHtml } from 'scenic-prism-standalone';
+ *
+ * const html = buildStandaloneHtml(spec);
+ * const source = highlightStandaloneHtml(html, { dark: true });
+ * ```
+ *
+ * `wrap` is the one choice about the shape of it: off, the source sits in a
+ * `<pre>` and long lines scroll; on, there is no `<pre>` at all and they fold
+ * to the window instead.
+ *
+ * For the same colouring inside a page of your own, see
+ * {@link highlightStandaloneHtmlFragment}, which returns the markup and the
+ * stylesheet separately and wraps neither.
+ */
+export declare function highlightStandaloneHtml(html: string, options?: HighlightOptions): string;