scenic-prism-standalone 0.1.0

package/LICENSE

@@ -0,0 +1,133 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+Required Notice: Copyright James Porter (https://scenic-prism.pages.dev/license)
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose. However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software. Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software. For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization,
+or government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else. These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice. Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+**_As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim._**
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization. **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise. Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.

package/README.md

@@ -0,0 +1,202 @@
+# scenic-prism-standalone
+
+A [`scenic-prism`](https://www.npmjs.com/package/scenic-prism) scene, as one
+self-contained file: an HTML page that needs nothing, or a React component that
+needs only React. Inside each is the scene's WGSL and a WebGPU loop.
+
+```ts
+import { backgrounds, buildStandaloneHtml, materials, plane, sphere } from 'scenic-prism-standalone';
+import { writeFileSync } from 'node:fs';
+
+const SCENE = {
+  scene: sphere(1).paint(materials.chrome).union(plane([0, 1, 0], -1)),
+  background: backgrounds.dusk,
+};
+
+writeFileSync('chrome.html', buildStandaloneHtml(SCENE, { size: 900, seed: 7, min: true }));
+```
+
+The generated HTML contains the compiled shaders, a canvas and a render loop.
+It needs no external scripts or assets and works offline in a browser with
+WebGPU.
+
+## Install
+
+```sh
+npm install scenic-prism-standalone
+# or: pnpm add scenic-prism-standalone
+```
+
+The package includes `scenic-prism` and `scenic-prism-fluent` at exact versions
+and re-exports their main APIs. It ships ESM with TypeScript declarations.
+You can generate files in Node or in a browser.
+
+## `buildStandaloneHtml(spec, options?)`
+
+Compiles `spec` and returns the document as a string. Where that string goes —
+a file, an HTTP response, an `<iframe srcdoc>` — is yours.
+
+| Option | | |
+| --- | --- | --- |
+| `size` | `number` | Square backing resolution in pixels (default 1024). |
+| `width` `height` | `number` | The same, when the canvas is not square. |
+| `maxFrames` | `number` | Samples per pixel to accumulate before stopping (default 1200). |
+| `bounces` | `number` | Light-bounce budget, baked into the shader (default 6). |
+| `tone` | `'aces' \| 'reinhard' \| 'linear'` | The curve that brings the traced light into display range (default `'aces'`). |
+| `exposure` | `number` | Exposure in stops, before that curve: `-1` is half as bright, `+2` four times (default 0). The page has no controls, so this is the only chance to set it. |
+| `colorSpace` | `'srgb' \| 'display-p3'` | Which colour space the render is shown in (default `'srgb'`). `'display-p3'` asks the canvas for the wider gamut of a modern screen; a browser without one stays in sRGB. |
+| `alpha` | `boolean` | Trace onto a transparent background; the page's own backdrop becomes a chequer (default false). |
+| `seed` | `number` | Fix the sample sequence, so every visitor sees the same noise. |
+| `min` | `boolean` | Minify the markup, the stylesheet, the script and the shader. |
+| `title` | `string` | The document's `<title>` (default `scenic-prism`). |
+
+`width` and `height` are the canvas's **backing store**, and so what the shader
+is compiled for. How large the page draws it is the stylesheet's business: it is
+centred and fitted to the window, so a 2048-pixel render is still a 2048-pixel
+render on a phone.
+
+## `buildStandaloneTsx(spec, options?)`
+
+Returns the scene as a `.tsx` file for a React project. The generated component
+imports only `react`; the shaders and render loop are included in the file.
+
+```ts
+import { backgrounds, buildStandaloneTsx, materials, sphere } from 'scenic-prism-standalone';
+import { writeFileSync } from 'node:fs';
+
+writeFileSync(
+  'src/ChromeSphere.tsx',
+  buildStandaloneTsx(SCENE, { componentName: 'ChromeSphere', size: 900, seed: 7 }),
+);
+```
+
+```tsx
+import { ChromeSphere } from './ChromeSphere';
+
+<ChromeSphere size={720} className="rounded-xl" />;
+```
+
+The component renders a single `<canvas>` and forwards canvas props to it.
+Set its display size and appearance with CSS.
+
+| Option | | |
+| --- | --- | --- |
+| `componentName` | `string` | The component's name, and so the name to import it by (default `Scene`). Its props interface is exported alongside it as this plus `Props`. |
+| `size` | `number` | Backing resolution the `size` prop *defaults* to (default 1024). |
+| `width` `height` | `number` | The same, when the canvas is not square. |
+| `maxFrames` | `number` | Samples per pixel the `maxFrames` prop defaults to (default 1200). |
+| `bounces` | `number` | Light-bounce budget, baked into the shader (default 6). |
+| `tone` | `'aces' \| 'reinhard' \| 'linear'` | The curve that brings the traced light into display range (default `'aces'`). |
+| `exposure` | `number` | Exposure in stops, before that curve (default 0). |
+| `colorSpace` | `'srgb' \| 'display-p3'` | Which colour space the render is shown in (default `'srgb'`). `'display-p3'` asks the canvas for the wider gamut of a modern screen; a browser without one stays in sRGB. |
+| `alpha` | `boolean` | Trace onto a transparent background, so whatever the canvas sits on shows through (default false). |
+| `seed` | `number` | The seed the `seed` prop defaults to. Without one, a fresh sample sequence on every mount. |
+| `min` | `boolean` | Minify the two shaders while leaving the component code readable. |
+| `useClient` | `boolean` | Prepend `'use client'`, for a framework that renders on the server first (default false). |
+| `exportDefault` | `boolean` | Also export the component as the module's default (default false). The named export is always there. |
+
+The first five of those are only *defaults*, because the component takes them as
+props too:
+
+| Prop | | |
+| --- | --- | --- |
+| `size` | `number` | Square backing resolution in pixels; `width`/`height` override it. |
+| `width` `height` | `number` | The backing store, not the CSS box. |
+| `maxFrames` | `number` | Stop accumulating after this many samples per pixel. |
+| `seed` | `number \| null` | Fix the sample sequence, or `null` for a fresh one. |
+| `onProgress` | `(frames, total) => void` | Called after every accumulated frame. |
+| `onDone` | `(frames) => void` | Called once the accumulation finishes. |
+| `onError` | `(error) => void` | Called if rendering cannot start — no WebGPU, or a hand-written WGSL function that does not compile, in the compiler's own words. Use it to show your own fallback. |
+
+…plus everything a `<canvas>` accepts. The resolution is a uniform rather than a
+literal in the shader, which is what lets the size be a prop at all; `bounces`,
+`tone`, `exposure`, `colorSpace` and `alpha` are baked in when the file is written, where
+there is still a spec to compile, and so are not.
+
+Changing the size restarts the accumulation. Each mount requests a GPU device of
+its own, and unmounting destroys it — and every buffer and pipeline on it with
+it. The generated file uses TypeScript's DOM WebGPU types, which ship with
+TypeScript 6 and later.
+
+## `downloadStandaloneHtml(spec, options?)`
+
+The same page, saved by the browser it is called in — an export button, in one
+call. Takes everything `buildStandaloneHtml` does plus `filename` (default
+`scene.html`; `.html` is appended if it is missing), and returns the same HTML
+string, so a caller that also wants to show or measure what it saved need not
+build it twice.
+
+```tsx
+<button onClick={() => downloadStandaloneHtml(SCENE, { size: 900, min: true })}>
+  Download this scene
+</button>
+```
+
+## `min`
+
+`min` strips the comments and squeezes the whitespace out of all four languages
+in the page. It **renames nothing and reorders nothing** — an identifier in a
+minified page is the identifier this package wrote, and the shader is the same
+shader — so the two modes differ in size and in nothing else. Roughly a third
+comes off a typical page; the shader is most of what is left, and most of that
+is the scene.
+
+In a `.tsx` file it squeezes the two shaders and stops there: the component
+around them is yours to read and edit, and whatever bundles it will minify it
+anyway.
+
+Leave it off while you are working — the readable file is the best description
+of what the library actually does at runtime — and turn it on for what you ship.
+
+## What is in the page
+
+```
+<canvas>            the backing store, at the size you asked for
+<style>             centre it, fit it to the window, nothing else
+<script>
+  WIDTH … SEED      the constants you passed
+  TRACE             your scene, compiled to a WGSL compute shader
+  DISPLAY           exposure, tonemap and gamma, accumulation buffer to canvas
+  the loop          one float storage buffer, one sample per pixel per frame
+```
+
+The loop is `scenic-prism`'s own renderer with everything a *library* needs
+taken out — no handle, no shared device, no teardown, no progress callback —
+because a page that draws one picture and stops has nobody to hand any of that
+to. A browser without WebGPU gets a line of text saying so instead of a black
+rectangle, and a scene whose hand-written WGSL does not compile gets the
+compiler's reason under it.
+
+The `.tsx` file is the same two shaders and the same loop, put back inside a
+React effect, which is what gives it the teardown and the callbacks a page has
+nobody to hand: it is `scenic-prism-react`'s component with the library taken
+out rather than the renderer with the library taken out.
+
+## The companion packages
+
+| Package | |
+| --- | --- |
+| [`scenic-prism`](https://www.npmjs.com/package/scenic-prism) | The library: scenes, the compiler, the renderer. |
+| [`scenic-prism-fluent`](https://www.npmjs.com/package/scenic-prism-fluent) | The same vocabulary, chained. |
+| [`scenic-prism-react`](https://www.npmjs.com/package/scenic-prism-react) | The renderer as a React component — the library kept, the scene still a scene. |
+| [`scenic-prism-playwright`](https://www.npmjs.com/package/scenic-prism-playwright) | Scenes to image files, from Node. |
+
+All of them are released together and carry the same version.
+
+## Licence
+
+[PolyForm Noncommercial 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0).
+
+Free for any **noncommercial** purpose — personal projects, study, experiments,
+hobby and amateur work, teaching, and use by charities, schools, universities,
+public research bodies, public health and safety organisations and government,
+whoever is funding them. Change it, build on it and redistribute it on those
+same terms, passing on the licence and its `Required Notice:` line with any copy.
+
+**Commercial use needs a separate licence.** If you want to use `scenic-prism`
+in or around a commercial product, ask via
+[the repository](https://github.com/jamesporter/Scenic-Draft).
+
+The terms in full are in the `LICENSE` file shipped inside this package, and
+explained in plain language at
+[scenic-prism.pages.dev/license](https://scenic-prism.pages.dev/license).

package/dist/component.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The TypeScript that goes in the `.tsx` file.
+ *
+ * This is `scenic-prism-react`'s `SceneRenderer` with the library taken out, in
+ * the same way `runtime.ts` is the core renderer with the library taken out.
+ * The scene has already become a shader by the time this runs, so what is left
+ * is one component holding one canvas: ask for a GPU, build two pipelines,
+ * allocate one float buffer, and add one sample per pixel per animation frame
+ * until the budget is spent — inside an effect, so it starts when the component
+ * mounts, restarts when the size changes and gives its GPU back when it
+ * unmounts.
+ *
+ * Everything here is emitted verbatim into a file somebody else's build will
+ * compile, so two rules hold. It must type-check under `strict` against a
+ * consumer's own React and DOM library — which is why the WebGPU flags are
+ * written as numbers, since TypeScript's DOM library declares the device API
+ * but not the `GPUBufferUsage` namespace. And it may import nothing but
+ * `react`: the point of the file is that there is nothing to add to the
+ * project it is pasted into.
+ */
+import type { ColorSpace } from 'scenic-prism';
+/** The values `buildStandaloneTsx` bakes into the top of the file. */
+export interface ComponentConfig {
+    /** The component's name; its props interface is this plus `Props`. */
+    name: string;
+    /** Default backing resolution, which the `size`/`width`/`height` props override. */
+    width: number;
+    height: number;
+    /** Default sample budget, which the `maxFrames` prop overrides. */
+    maxFrames: number;
+    /** A fixed base seed, or `null` for a fresh sample sequence on every mount. */
+    seed: number | null;
+    /** The tracer's workgroup, which the image is divided by to dispatch it. */
+    workgroup: readonly [number, number];
+    /** The two shader sources: the scene's compute pass, and the tonemap. */
+    trace: string;
+    display: string;
+    /** Which colour space the component shows the render in. */
+    colorSpace: ColorSpace;
+    /** Whether the render has a transparent background, and so composites. */
+    alpha: boolean;
+    /** Prepend `'use client'`, for a framework that renders on the server first. */
+    useClient: boolean;
+    /** Add `export default <name>` under the component. */
+    exportDefault: boolean;
+}
+/**
+ * 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 declare function componentSource(config: ComponentConfig, min?: boolean): string;