@elastic/isomer-studio 0.0.0 → 0.4.0

package/docs/ci.md

@@ -0,0 +1,55 @@
+---
+navigation_title: In CI
+description: Run isomer-studio check and build in GitHub Actions with the composite action, and upload the report and the site.
+---
+
+# In CI
+
+`check` is the gate: it exits 1 when any example fails to validate or render. `build` is the preview: upload the site and every PR gets a Studio a reviewer can download.
+
+## The GitHub Action
+
+The Isomer repository has a composite action that runs both and uploads what they write. It runs the `isomer-studio` binary installed in `working-directory`, so install the pack's dependencies, `@elastic/isomer-studio` among them, first. Then:
+
+```yaml
+- uses: elastic/isomer/.github/actions/isomer-studio@main
+  with:
+    config: isomer-studio.config.ts
+```
+
+| Input | Default | What it does |
+| --- | --- | --- |
+| `config` | Required | The config, relative to `working-directory`. |
+| `working-directory` | `.` | Where the `isomer-studio` command resolves. `config`, `out` and `report` resolve against it. |
+| `check` | `true` | Runs `check`, writing a JUnit report. A failure fails the step. |
+| `png` | `false` | Adds `--png` to the check. |
+| `report` | `isomer-studio-report.xml` | Where the report goes. It uploads as `<artifact-name>-report`, even when the check fails. |
+| `build` | `true` | Runs `build`, even when the check failed. |
+| `out` | `dist/studio` | Where the site goes. |
+| `base` | `./` | The URL path the site is served from. |
+| `artifact-name` | `isomer-studio` | The name of the uploaded site. |
+
+The Isomer repository runs it on the slides pack in its own CI, after `pnpm verify`.
+
+## Without the action
+
+The action is two commands. On another CI system, run them yourself:
+
+```sh
+npx isomer-studio check --config isomer-studio.config.ts --format junit --report isomer-studio-report.xml
+npx isomer-studio build --config isomer-studio.config.ts --out dist/studio
+```
+
+`npx @elastic/isomer-studio check` also works without installing the Studio, but an installed one keeps CI on the version the lockfile pins.
+
+`build` and `check --png` rasterize with `@elastic/isomer-image-takumi`, a native dependency the Studio installs for the platform it runs on.
+
+## Deploying with docs
+
+To serve the Studio from a docs site, build it into the site's output with the path it will be served from:
+
+```sh
+npx isomer-studio build --config isomer-studio.config.ts --out site/studio-app --base /my-docs/studio-app/
+```
+
+Give the app its own directory, not the one the Studio's or the pack's docs build into, so neither overwrites the other.

package/docs/commands.md

@@ -0,0 +1,167 @@
+---
+navigation_title: Commands
+description: The flags of isomer-studio init, dev, build and check, the config init writes, the files a build writes, and what a static site can and cannot do.
+---
+
+# Commands
+
+```text
+isomer-studio [command] [options]
+```
+
+With no command, `isomer-studio` runs `dev`. Every command takes these options:
+
+| Option               | Default               | What it does                                                                                    |
+| -------------------- | --------------------- | ----------------------------------------------------------------------------------------------- |
+| `--cwd <dir>`        | The current directory | The project. Resolves `--config`, `--out` and `--report`.                                       |
+| `--loader tsx\|none` | `tsx`                 | How the config is imported in Node. See [How the config loads](config.md#how-the-config-loads). |
+
+`dev`, `build` and `check` also take `--config <file>`, which defaults to `isomer-studio.config.ts`, `.tsx` or `.js` in `--cwd`. Without a config they stop and say to run `init`.
+
+The exit code is 0 on success, 1 when a command fails or `check` finds a failure, and 2 on bad usage, which also prints the usage text. `isomer-studio help` and `-h` print it too.
+
+## `init`
+
+```sh
+npx @elastic/isomer-studio init
+```
+
+Writes a config that default-exports `defineStudioConfig({ title, runtime })`, registering by name each pack the package's entry exports: `isomer-studio.config.ts` beside a `tsconfig.json`, `isomer-studio.config.js` otherwise. Add `previewExample`, `stylesheet` or apps to it as the pack needs; see [The config](config.md). It stops when a config already exists or the entry exports no pack.
+
+The entry is the first of `src/index` and `index`, as `.tsx`, `.ts`, `.jsx` or `.js`, that exists, then the `package.json` root export (following its `import`, `module`, `require`, `node` and `default` conditions, nested ones included), `module` or `main`. Every export shaped like `definePrimitivePack`'s result is a pack: named exports, the default export, and the properties of a default-exported object. A pack exported under more than one name is registered once, and a pack whose name the config's own imports take is imported under another. The title is the `package.json` `name`.
+
+The project needs React 18, `@elastic/isomer-sdk` and `zod`, which a pack has already. `@elastic/isomer-runtime` and `@elastic/isomer-studio` come from the Studio's own install when the project lacks them; see [How the config loads](config.md#how-the-config-loads).
+
+## `dev`
+
+```sh
+npx @elastic/isomer-studio dev --port 5179 --open
+```
+
+Serves the Studio on `127.0.0.1` and prints its URL.
+
+| Option            | Default | What it does                             |
+| ----------------- | ------- | ---------------------------------------- |
+| `--port <number>` | `5179`  | `0` picks a free port.                   |
+| `--open`          | Off     | Opens the Studio in the default browser. |
+
+The server runs on Vite. When the config or anything it imports changes, the Studio re-renders in place with the new config: the page does not reload, so the route, the editor's text and every panel's state survive. The server re-runs the same modules in Node before the page updates, so PNGs never show a stale pack. A syntax error shows Vite's error overlay, and the Studio picks up again once the file is fixed. The editor compiles JSX on the server, and the PNG preview rasterizes the composition being edited.
+
+### Comparing outputs
+
+Workbench combines browser renders in one **Web** panel, labeled **HTML / React /
+Snapshot** beneath its title, without a per-panel dropdown. HTML and its stylesheet
+render in a shadow root, not an iframe; its links open in a new tab so following one
+never unloads the draft. PNG stays separate; Slack, Markdown and
+Text appear below. The **Outputs** menu lists these displayed outputs rather than
+separate React and Snapshot entries when HTML is available. Workbench starts with every
+output selected; pick one to inspect it at full size, or add others to compare.
+Runtimes without HTML retain their React or Snapshot output.
+
+**Enhancements**, aligned at the right of the Web header, is off by default.
+The menu tests each registered enhancement's `appliesTo` predicate against the
+current composition, including nested primitives through the runtime's child
+walker. Only applicable enhancements appear. A dropdown showing the selected and
+applicable counts (such as **Enhancements (0/1)**) lets you enable each
+independently. Each is listed by its `name` and `description`, falling back to its
+id (such as `slideCopy` or `slideBuilds`) when it has no `name`.
+Enhancements without a script are host-driven;
+selecting one enables its render-time behavior but does not supply host controls
+such as advancing a slide build. Scripted enhancements run on the HTML preview through the SDK's
+host-run enhancement helper. Turning them off
+remounts the unenhanced preview so script-created elements and listeners do not
+linger. Only explicitly requested pack scripts run; embedded script elements are
+not executed. The controls are disabled for Snapshot, in Source view, when no
+enhancements are registered, or for a React-only preview without
+`createReactContext` or `stylesheet`. Snapshot retains its fixed frame, theme resolution and
+visibility rules. Sharing a panel is not a claim of pixel equality.
+
+Studio does not install or launch a headless browser to capture previews.
+It does not report pixel-difference percentages or infer matching outputs.
+DOM or markup similarity is not proof of identical rendered
+pixels. PNG previews still use Takumi, not a browser screenshot.
+
+The editor, outputs, and prop drawer share one panel, with a resizer between
+the borderless columns and independent scrolling in each. Its bottom strip has **Props** at the
+left and validity at the right. Copy sits beside the source-format controls in
+the editor as a compact icon with a tooltip. Output previews always form a
+single vertical list, even in wide columns. Each output has a solid header against
+the recessed output canvas in both color modes. The shared footer owns its top
+divider; the editor has no additional bottom border.
+**Props** toggles a full-width drawer, collapsed by default. Component
+tabs select one schema-derived table for the selected primitive or its branded
+JSX child components (including nested members).
+It also includes other primitives in the draft and their children, rather than
+offering a `+ Prop` action that edits only the first node. Tables are read-only;
+edit props in JSX or JSON. Name, type and description columns use proportional
+widths and top-aligned cells. The drawer sits outside the editor/output resizer,
+so adjusting the split does not narrow the reference.
+The 72-pixel collapsed navigation rail uses full-opacity white icons in centered,
+32-pixel buttons. Its toggle stays fixed while the grouped entries scroll
+vertically when they exceed the available height.
+The white sidebar toggle sits beside the filter, using `transitionRightIn` to
+collapse and `transitionLeftIn` to expand. At 1120 pixels or narrower, navigation
+starts collapsed, expands over the content when toggled, and does not expand on
+hover. Component tabs replace prop section
+headings and label the active table for assistive technology.
+Slack's preview padding uses the message canvas
+background in both color modes.
+
+## `build`
+
+```sh
+npx @elastic/isomer-studio build --out dist/studio --base /studio/
+```
+
+Writes the Studio as a static site.
+
+| Option          | Default       | What it does                                                                                                                                   |
+| --------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--out <dir>`   | `dist/studio` | Where the site goes. A previous build there, marked by its `.isomer-studio-build` file, is replaced; any other non-empty directory is refused. |
+| `--base <path>` | `./`          | The URL path the site is served from. A trailing slash is added.                                                                               |
+
+Every URL in the site resolves against `--base`, so the same build works at a domain's root or under a sub-path. Routes live in the URL's hash, so the host needs no rewrites. A `./` base works when the site is opened from any single directory, such as an unzipped CI artifact behind a static server.
+
+```text
+<out>/index.html
+<out>/assets/app.js, assets/chunks/*   # the Studio and the config
+<out>/assets/app.css                    # every stylesheet the config imports, apps included
+<out>/assets/media/*                    # fonts and images those stylesheets reference
+<out>/assets/studio.css                 # the Studio's chrome and Monaco's stylesheet
+<out>/assets/codicon-<hash>.ttf         # Monaco's icon font
+<out>/assets/editor.worker.js, ts.worker.js, json.worker.js
+<out>/assets/slack.css                  # the Slack preview's stylesheet
+<out>/assets/esbuild.wasm               # compiles JSX in the browser
+<out>/png/manifest.json, png/<key>.png  # when the runtime has a snapshot surface
+```
+
+### Static sites
+
+A static site has no server, so two things work differently from `dev`:
+
+- **JSX** compiles in the browser with `esbuild-wasm`, fetched the first time the editor needs it.
+- **PNGs** are prerendered. `build` composes every example in both themes through the config's `compose` or `previewExample`, rasterizes each one, and names the file by the SHA-256 of the composition's canonical JSON. The page computes the same key and fetches the file. An edited composition has no file, so the PNG preview says "PNG previews of edited compositions need `isomer-studio dev`." An example that fails to compose or rasterize is reported and left out; the build still succeeds.
+
+## `check`
+
+```sh
+npx @elastic/isomer-studio check --format junit --report studio-report.xml --png
+```
+
+Validates and renders every example of every primitive, composed through the config's `compose` or `previewExample`, without a browser. It prints each failure and the totals, and exits 1 on any failure.
+
+| Option                 | Default                       | What it does                                                                             |
+| ---------------------- | ----------------------------- | ---------------------------------------------------------------------------------------- |
+| `--report <file>`      | None                          | Also writes the report to a file.                                                        |
+| `--format json\|junit` | `json`                        | The report's format. JUnit has a test suite per primitive and a test case per check.     |
+| `--png`                | Off                           | Also rasterizes every example. Needs a snapshot surface.                                 |
+| `--surfaces <list>`    | Every surface the runtime has | A comma-separated subset of `react`, `html`, `snapshot`, `slack`, `markdown` and `text`. |
+
+For each primitive and example, `check` runs:
+
+- **`icon`:** the primitive has an icon, from the pack's `icons` or its definition, and it passes `assertPackIconsValid`.
+- **`props`:** the composed example validates against the runtime. When it throws or the composition is invalid, every surface for that example is skipped.
+- **One check per surface:** the surface renders without throwing. React renders through `react-dom/server` from the config's React. Slack output is also held to `SLACK_LIMITS` from `@elastic/isomer-sdk/slack`, and fails on a block wrapped in `unmodeledSlackBlock` whose type Isomer now models. A surface the primitive has no native renderer for is skipped, not failed.
+- **`png`,** with `--png`: the composition rasterizes.
+
+`check` renders the light theme.

package/docs/config.md

@@ -0,0 +1,192 @@
+---
+navigation_title: The config
+description: What an isomer-studio.config.ts exports, how previewExample and compose wrap examples, how apps add pages, and how the Studio loads the config in Node and the browser.
+---
+
+# The config
+
+A config file default-exports `defineStudioConfig({ ... })`. `defineStudioConfig` returns its argument; it exists so the object is typed. The runtime exports are `defineStudioConfig` and `adoptStylesheet`. The types are `StudioConfig`, `StudioCompose`, `StudioRuntime`, `StudioTheme`, and, for [apps](#apps), `StudioApp`, `StudioAppPage`, `StudioAppProps`, `StudioAppSurface`, `StudioPreviewProps`, `StudioSurfaceProps`, `PreviewZoom` and `RenderPdf`.
+
+```ts
+import { createIsomerRuntime } from '@elastic/isomer-runtime';
+import { defineStudioConfig } from '@elastic/isomer-studio';
+
+import { previewSlide } from './src/examples/preview_slide';
+import { slideDeckFrame, slidesPack, slideStylesheet } from './src/index';
+
+export default defineStudioConfig({
+  runtime: createIsomerRuntime({
+    packs: [slidesPack],
+    frames: { slide: slideDeckFrame },
+  }),
+  stylesheet: slideStylesheet,
+  previewExample: previewSlide,
+});
+```
+
+| Field                       | Required | What it does                                                                                                                                                                                                                                                                                                  |
+| --------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `runtime`                   | Yes      | The runtime from `createIsomerRuntime`. Its packs are what the Studio lists, and its surfaces are the previews it offers.                                                                                                                                                                                     |
+| `title`                     | No       | Replaces the header, the page title, and the `check` report name. Defaults to `Isomer Studio`. Leave it unset to keep the product name; a runtime with more than one pack shows each pack in the nav.                                                                                                         |
+| `stylesheet()`              | No       | The CSS the React preview needs. The Studio calls it once and adopts the result into each preview's shadow root.                                                                                                                                                                                              |
+| `createReactContext(root)`  | No       | Returns the render context the pack's renderers expect, inside the React preview's shadow root, after `stylesheet` is adopted there. Call `adoptStylesheet(root, css)` for any other CSS. Without it the context is empty, and without it or `stylesheet` the React preview shows the `html` surface instead. |
+| `previewExample(node)`      | No       | The composition one node is shown in on its own, such as a slide around it. The Studio adds the theme and puts several nodes in a `view`. See [`previewExample` and `compose`](#previewexample-and-compose).                                                                                                  |
+| `compose(nodes, { theme })` | No       | Wraps example nodes in a composition, for full control. Wins over `previewExample`. Defaults to `{ type: 'view', body: nodes, theme }`.                                                                                                                                                                       |
+| `apps`                      | No       | Pages that demonstrate the pack, listed in the nav and on Home. See [Apps](#apps).                                                                                                                                                                                                                            |
+| `imageFonts`                | No       | A module path, relative to the config, whose default export lists the takumi `FontLoader`s PNGs and PDFs draw text with. See [Image fonts](#image-fonts).                                                                                                                                                     |
+| `featured`                  | No       | Primitive types Home features, in order. Without it Home draws six at random on each load. See [Featured primitives](#featured-primitives).                                                                                                                                                                   |
+
+## `previewExample` and `compose`
+
+Examples are nodes, not compositions. Every place the Studio needs a composition, the config's `compose`, or its `previewExample`, builds it: the gallery, the docs pages, the editor's preview, the PNGs a static build prerenders and every example `check` renders. A pack writes the envelope once and every mode agrees on it.
+
+The default fits a pack whose primitives render inside a plain `view`. A pack whose frame requires a particular root says how one node is shown with `previewExample`. The slides frame draws exactly one `slideFrame`, so the slides `previewExample` wraps a lone node in a preview slide, and passes a node that is already a `slideFrame` through unwrapped. `compose` replaces both when a pack needs to shape several nodes too.
+
+`compose` receives the theme the Studio is showing, `light` or `dark`, and puts it on the composition; with `previewExample`, the Studio does. That theme is the app's color mode, so previews always match the chrome around them. Light and dark are then different compositions, which is how a static build tells their PNGs apart.
+
+## Featured primitives
+
+Home opens with a strip of featured primitives, each with a link to its Reference page and to the Workbench. `featured` names them by type, in the order they appear:
+
+```ts
+export default defineStudioConfig({
+  runtime,
+  featured: ['titleSlide', 'slideBulletList', 'slideSplitLayout'],
+});
+```
+
+Without `featured`, Home draws six primitives at random each time it loads, so a pack with no opinion still shows its range. `dev`, `build` and `check` reject a `featured` entry the runtime has no primitive for, or one listed twice, and name it. A browser hot update with an invalid entry reports it and skips it.
+
+## Apps
+
+An app is a whole page of the Studio, such as a deck viewer. Each one gets a top-level nav entry beside Gallery, a tile on Home, and a route at `#/app/<id>/`.
+
+```ts
+export default defineStudioConfig({
+  runtime,
+  apps: [
+    {
+      id: 'decks',
+      title: 'Decks',
+      description: 'Whole presentations, played one slide at a time.',
+      load: () => import('./studio/decks_app'),
+    },
+  ],
+});
+```
+
+| Field         | Required | What it does                                                                                                                        |
+| ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `id`          | Yes      | The route segment, matching `/^[a-z][a-z0-9-]*$/` and unique within the config.                                                     |
+| `title`       | Yes      | The nav entry, the header's label while the app is open, and the Home tile's title.                                                 |
+| `description` | No       | One line under the title on the Home tile and in Home's Loaded panel.                                                               |
+| `icon`        | No       | A `PrimitiveIcon`, held to the same rules as a primitive's icon by `check`. Without one, the nav and Home show the title's initial. |
+| `load`        | Yes      | Imports a module whose default export is the app's page.                                                                            |
+| `pages`       | No       | Nav rows under the app's own row. See [Pages](#pages).                                                                              |
+
+`dev`, `build` and `check` reject invalid apps and name each one. A hot update with invalid apps keeps the last valid ones and shows why. `check` counts the apps but never calls `load`.
+
+### Pages
+
+An app can list its own pages in the nav, such as one per deck. The nav shows them without loading the app, so a config builds them from data it already imports.
+
+```ts
+pages: [
+  { path: 'isomer', title: 'Isomer', section: 'Decks' },
+  { path: 'distillate', title: 'Distillate', section: 'Decks' },
+],
+```
+
+| Field     | Required | What it does                                                                                                       |
+| --------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
+| `path`    | Yes      | Opens `#/app/<id>/<path>`. One or more non-empty segments, with no leading or trailing `/`, unique within the app. |
+| `title`   | Yes      | The row's label. The nav filter matches it.                                                                        |
+| `section` | No       | Pages with the same `section` are listed under it, in order of first appearance. Pages without one come first.     |
+
+A page is current when the app's `path` equals the page's `path` or starts with it plus `/`. The longest match wins, so `isomer/3` keeps a page at `isomer/3` current over one at `isomer`. While a page is current, the app's own row is not. The collapsed rail shows only the app's row.
+
+`dev`, `build` and `check` reject invalid pages as they do invalid apps, naming the app and the page's index.
+
+### The page
+
+The page is a React component, and the Studio hands it `StudioAppProps`:
+
+| Prop             | What it is                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Preview`        | Renders pack output inside a shadow root, isolated from the app's styles and the Studio's. Pass `nodes`, which go through the config's `compose` or `previewExample` at the current theme, or a finished `composition`. `zoom` defaults to `fit`, and `maxHeight` caps a fitted preview's height. `heading={false}` leaves out the composition's leading title, as a slide shown on its own wants. `enhancements` are enhancement ids the surface renders with, such as the slides pack's `SLIDE_BUILDS`. `onCommit(root)` runs with the shadow root after each render commits, for a host step such as `showSlideBuild`. Without `createReactContext` or `stylesheet`, it shows the `html` surface, which gets `enhancements` but has no shadow root, so `onCommit` is never called. |
+| `Surface`        | Shows a `composition` on one of `surfaces`, as the Studio's own previews do: `surface` picks it, `view` is `render` or `source`, and `zoom` and `heading` work as on `Preview`. `png` is drawn by the host.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `surfaces`       | The `{ id, label }` surfaces `Surface` can show, in the Studio's order: the runtime's, then `png` when the host rasterizes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `renderPdf`      | `renderPdf(compositions, { title })` resolves to a PDF `Blob`, a page per composition, drawn as PNGs are. Only `dev` has one; it is `undefined` in a static build.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `runtime`        | The config's runtime.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `theme`          | `light` or `dark`, following the Studio's color mode.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `path`           | Everything after `#/app/<id>/`, slashes included, with each segment percent-decoded.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `navigate(path)` | Moves to another `path` within the app, adding a history entry. Each segment is percent-encoded in the hash, so `path` reads back the same after a reload.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+
+Import only types from `@elastic/isomer-studio` in an app module. The Studio hands the page everything it needs as props.
+
+The page stays mounted when `path`, the theme or the config changes. When the config changes, the Studio calls the new `load` and remounts the page only if the module's default export is a different component. Edits to the app module update it in place through React Fast Refresh, as long as the module exports only components. A module that exports anything else re-runs the config instead.
+
+`load` runs only in the browser. Node imports the config for `check` and `build`, but never calls `load`, so code that must stay off the server belongs behind it.
+
+### EUI
+
+Apps render under the Studio's own `EuiProvider`. Use EUI components directly, and nest `EuiThemeProvider` to change the theme for part of the page. Never mount a second `EuiProvider`.
+
+EUI's theme and Emotion's cache reach the app only when it imports the same copies the Studio does. When a config with apps resolves `@elastic/eui` or `@emotion/react`, it must resolve the Studio's copy, and `dev`, `build` and `check` stop when it does not. A config without apps is not checked. Install the Studio's versions of EUI and its peers beside the config: `@elastic/eui`, `@elastic/eui-theme-borealis`, `@elastic/datemath`, `@emotion/react`, `@emotion/css` and `moment`.
+
+Apps are not inside a shadow root, because EUI's popovers, flyouts, modals and toasts portal to `document.body`.
+
+### CSS
+
+| Form                        | Scope  | Notes                                                                                                                                                                                                         |
+| --------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Emotion's `css`             | Scoped | Needs `@emotion/react` as the JSX import source: add `/** @jsxImportSource @emotion/react */` to the file, or set `jsxImportSource` in a `tsconfig.json` for the app's folder.                                |
+| CSS Modules, `*.module.css` | Scoped | TypeScript needs a declaration such as `declare module '*.module.css' { const classes: Readonly<Record<string, string>>; export default classes; }`.                                                          |
+| Plain `.css`                | Global | Scope its selectors under the app's root element. `url()`s to fonts (`woff2`, `woff`, `ttf`, `otf`, `eot`) and images (`png`, `jpg`, `jpeg`, `gif`, `webp`, `avif`, `svg`, `ico`) resolve under any `--base`. |
+
+In `dev`, a stylesheet loads when the app first opens. A static build bundles every stylesheet the config imports into `assets/app.css`, which loads with the page.
+
+## Surfaces a runtime may lack
+
+The Studio offers the surfaces `runtime.surfaces` has. A runtime without a frame has no `snapshot` surface, so it gets no Snapshot or PNG previews, a static build prerenders no PNGs, and `check` reports those checks as skipped.
+
+## Image fonts
+
+PNGs and PDFs are drawn by takumi in Node, which knows no fonts but its own. `imageFonts` names a module that default-exports the faces to draw with, as `FontLoader[]` from `@elastic/isomer-image-takumi`:
+
+```ts
+// studio/image_fonts.ts
+export { slideFonts as default } from '../src/examples/fonts';
+```
+
+Node imports it the way it imports the config, the first time it draws, and the browser never does, so it may read font files from disk. `dev`, `build` and `check --png` all draw with it. Without it, PNGs fall back to takumi's built-in face and a PDF cannot draw text.
+
+## How the config loads
+
+The config runs in two places: in Node, for `check` and for the dev server's PNGs, and in the browser, bundled into the app.
+
+**In Node**, `check` and `build` import the config with `tsx`, which compiles TypeScript and JSX as it loads and leaves resolution to Node. The config, its pack, React and the runtime all resolve from the config's own directory, so they come from the pack's `node_modules`. `tsx` applies the `tsconfig.json` nearest the config, so the pack's `jsx` setting holds in both ES module and CommonJS projects.
+
+`dev` loads the config through Vite's server-side module graph instead, with the same nearest-`tsconfig.json` JSX settings. Packages in `node_modules` load once through Node, and an edit re-runs only the files that changed and the modules that import them.
+
+`--loader none` skips both and imports the config with a plain `import()`. Use it for a JavaScript config, or to bring another loader through `NODE_OPTIONS=--import ...`. Node caches that import, so under `dev` the browser picks up edits but PNGs keep the config and pack as they were at startup; restart `dev` to refresh them.
+
+**In the browser**, `build` bundles the config with esbuild and `dev` serves it through Vite. `react`, `react-dom` and their subpaths resolve as if imported from the config, so the Studio's own components, Emotion and the pack share one React, and each package's browser build is the one loaded.
+
+**Run with `npx`**, the Studio sits in npm's cache rather than the pack's `node_modules`. Two rules make that work in Node, Vite and esbuild alike:
+
+- `react`, `react-dom`, `@elastic/isomer-sdk` and `zod`, imported from outside the project, resolve from the project, so the runtime and the pack share them.
+- `@elastic/isomer-runtime` and `@elastic/isomer-studio`, when the project does not have them, resolve from the Studio's install. A config can import both without installing either.
+
+The project is the directory of the `package.json` nearest the config. In Node the rules cover `import` and `require`, which a `.ts` config in a project that is not `"type": "module"` loads through.
+
+## One React
+
+The Studio, the pack and the runtime must use one copy of React, and it must be React 18, which EUI requires. Before loading the config, the Studio resolves `react` from the config, stops when it is not 18, then resolves `react` from the `@elastic/isomer-runtime` the config sees, and stops when they differ:
+
+```text
+The Studio config and @elastic/isomer-runtime resolve different copies of React:
+  config:  /work/pack/node_modules/react
+  runtime: /work/pack/node_modules/@elastic/isomer-runtime/node_modules/react
+Install one React for both, for example by deduplicating your lockfile.
+```

package/docs/index.md

@@ -0,0 +1,96 @@
+---
+navigation_title: Isomer Studio
+description: A gallery, per-primitive Reference, a composition Workbench and a preview of every surface for any Isomer pack, run as a dev server, a static site or a CI check.
+---
+
+# Isomer Studio
+
+`@elastic/isomer-studio` is a learning and testing shell for any Isomer pack. Run it in a pack's package directory, and it shows:
+
+- a Home page with search, featured primitives, the pack's apps, and what the runtime loaded;
+- a gallery of every primitive, grouped as the pack's authoring groups are, whose React previews mount as they near the viewport;
+- a Reference page per primitive, with its purpose, guidance, props and live examples to teach its use;
+- a Workbench for editing a composition and seeing its live preview;
+- the same composition on every surface the runtime has: React, HTML, Snapshot, PNG, Slack, Markdown and text.
+
+It ships as a command-line tool, not a React library. EUI, Emotion and Monaco are bundled into it, so a pack never takes them as dependencies.
+
+```sh
+npx @elastic/isomer-studio init                                     # a config for the packs the package exports
+npx @elastic/isomer-studio                                          # a local server with hot updates
+npx @elastic/isomer-studio build --out dist/studio --base /studio/  # a static site
+npx @elastic/isomer-studio check --report studio-report.json        # a headless CI gate
+```
+
+Each command reads `isomer-studio.config.ts` (or `.tsx` or `.js`) from the current directory unless `--config` names another file, and without one says to run `init`; see [`init`](commands.md#init). Nothing needs installing first: the Studio uses the pack's React, SDK and zod, and brings the runtime. To pin the version and type-check a config, install `@elastic/isomer-studio` and `@elastic/isomer-runtime` as dev dependencies and run `npx isomer-studio`. In this repository, `pnpm studio:dev` runs the Studio from source against the slides pack.
+
+In the interface, **Reference** teaches how and when to use each primitive, while **Workbench** is where you edit compositions.
+
+![The Workbench: a composition's JSX beside its Web, PNG, Slack, Markdown and text output](images/workbench.png)
+
+## A first config
+
+`init` writes one like this, registering each pack the package's entry exports:
+
+```ts
+// isomer-studio.config.ts
+import { createIsomerRuntime } from '@elastic/isomer-runtime';
+import { defineStudioConfig } from '@elastic/isomer-studio';
+
+import { myPack } from './src/index';
+
+export default defineStudioConfig({
+  title: 'my-pack',
+  runtime: createIsomerRuntime({ packs: [myPack] }),
+});
+```
+
+That is enough for a pack whose primitives render inside a plain `view`. A pack with a frame that needs a particular root, or with styling the React surface must load, adds `previewExample` and `stylesheet`; see [The config](config.md).
+
+## The app
+
+![Home, with the primitive search, featured primitives, apps, and the packs and surfaces loaded](images/home.png)
+
+![The Reference page for the slides pack's pipeline primitive](images/reference.png)
+
+Home is a landing page for the configured developer workbench, not the introductory Isomer site. Its entry points and loaded-runtime panel reflect the packs and applications supplied by the host. The surface chart keeps its explanatory copy separate at every width, and reflows into a composition row above the surface cards when its column is narrow. Connecting lines follow the cards across wrapped rows.
+
+Studio is primarily a desktop learning and demo tool. When Home's main column is narrower than 620px, its application, learning, and featured tiles stack vertically. Featured primitives show three tiles per page, with Previous and Next buttons; the final gallery tile occupies a paging slot. Wider columns retain the horizontal strip. This is a readable narrow-window fallback, not a mobile Workbench.
+
+Home's Reference and Workbench actions keep the exact blue and teal from the Isomer logo. Featured and learning cards use deeper, opaque plum surfaces so their small action text stays readable without washing out the brand colors.
+
+Home exposes its primary column as the main landmark, with level-two headings for Featured primitives, Applications, and Learn more about Isomer. The loaded-runtime panel remains a separate complementary landmark.
+
+Links and buttons within Home use a white keyboard-focus outline that stays visible on the fixed dark palette, independently of the Workbench and Reference color mode.
+
+Home respects reduced-motion preferences: the surface chart keeps its focus and color feedback without scaling or lifting cards, and horizontal featured paging moves immediately instead of scrolling smoothly.
+
+- **Home.** An empty or unknown hash, `#/home`, and the mark in the header open Home. It has the primitive search, one chip per authoring group that opens the gallery at that group, the featured primitives (the config's `featured`, or six drawn at random) with Reference and Workbench links, a tile per app, three doors into the gallery, the Workbench and the Isomer documentation site, a chart of the surfaces the runtime has, and a panel of the packs, views, apps and surfaces loaded. With no apps or no views, the panel and the Applications row say how to add them and link to the Isomer documentation. Home keeps its own dark look; the color mode applies from Reference and Workbench on.
+- **Navigation.** With one pack, the sidebar lists primitives under that pack's authoring groups, in the pack's group order and alphabetically within each group. With more than one pack, each pack is a heading and its groups follow. Primitives no group claims are listed last, under Uncategorized. Each group collapses, the browser remembers which are closed, and a filter opens every group it matches. Resting the pointer on a name shows its first example and purpose.
+- **Surfaces.** The Workbench preview starts with every output selected, in one column at every width. The Outputs menu checks the outputs to compare: with every output selected, choosing one shows it at full size, and choosing another adds it. Rendered or Output source applies to every card at once. The Reference example card starts on the first surface, with the example picker on the left and the same menu on the right. Its view selector switches among Rendered, Output source, and Example source; the latter shows the example as JSX or JSON.
+- **Zoom.** With one surface picked, the preview's zoom menu scales the React, HTML, Snapshot and PNG previews: Fit width shrinks a preview to the panel's width and never enlarges it, and fixed levels run from 50% to 200%.
+- **Color mode.** The header offers Light, Dark, and System. System follows the operating system, including when it changes. The choice is remembered per browser, and previews render in the resolved mode. In dark mode the Workbench preview pane takes the theme's recessed background.
+
+## Requirements
+
+- Node 22.13 or later.
+- `react` and `react-dom` 18.2 or later, below 19, in the pack, because EUI's peer range stops there.
+- `@elastic/isomer-sdk` and `zod`, which the pack already has. `@elastic/isomer-runtime` comes with the Studio when the pack does not have it.
+
+The config, the pack and React load from the pack's own `node_modules`. The Studio stops when the pack's React is not 18, or when the config and `@elastic/isomer-runtime` see different copies of it.
+
+## The slides Studio
+
+This repository's reference pack has a config at `packages/isomer-primitives-slides/isomer-studio.config.ts`. Its Studio is deployed with these docs at [elastic.github.io/isomer/studio-app/](https://elastic.github.io/isomer/studio-app/), and every CI run uploads a build of it as the `slides-studio` artifact.
+
+These docs build in two places, and the app only in one:
+
+- GitHub Pages hosts the docs at `/isomer/studio/` and the app beside them at `/isomer/studio-app/`, so neither overwrites the other.
+- Codex previews of a docs change carry the docs only. Links to the app point at its Pages URL, and a PR's app preview is the CI artifact.
+
+## Known gaps
+
+- **PNGs of edited compositions.** A static site has PNGs for the examples it prerendered and nothing else; an edited composition shows "PNG previews of edited compositions need `isomer-studio dev`". See [Static sites](commands.md#static-sites).
+- **PDFs on a static site.** Only `dev` writes PDFs, so an app's `renderPdf` is `undefined` in a static build.
+- **Slack `tag` elements.** `slack-blocks-to-jsx` cannot draw rich-text `tag` elements, so toned values render blank in the Slack preview. The Block Kit is valid, so `check` passes it.
+- **Web fonts in the app.** The app loads no web fonts, so EUI's Inter falls back to the system font.

package/docs/toc.yml

@@ -0,0 +1,10 @@
+# Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+# or more contributor license agreements. Licensed under the Elastic License
+# 2.0; you may not use this file except in compliance with the Elastic License
+# 2.0.
+
+toc:
+  - file: index.md
+  - file: config.md
+  - file: commands.md
+  - file: ci.md