AI-native design editor. Open-source Figma alternative.
feat(demo): export the tour's chapter names (#1104)
Danila Poyarkov411f992c68e1
diff --git a/tools/AGENTS.md b/tools/AGENTS.mdindex 6da3044f7..f8ccb6af8 100644--- a/tools/AGENTS.md+++ b/tools/AGENTS.md@@ -37,7 +37,7 @@ Private tooling lives under `tools/<role>/<domain>/{src,tests}`; Steiger enforce## Demo document-The `/demo` document is a tour of eight chapters on one page, each a section stacked top to bottom, built from `tools/generate/demo/src/document/`: `theme.ts` (the Theme and App chrome collections, each with a Dark and a Light mode that `src/app/demo/theme.ts` switches by name to follow the app's theme; every color in the tour, icons included, is bound to them), `callout.tsx` (the Tip component every chapter instances, whose Where slot each fills with a piece of the app from `chrome.tsx`, drawn to the dark theme's tokens with the target ringed), `player/` (the player card, its artwork slot, and its controls with behaviours), and one file per chapter under `chapters/`, laid out by `chapters/chapter.ts` as numeral, heading, subject, and tip; `src/app/demo/viewport.ts` opens the tour on the first chapter. It renders design JSX through `document/icons.ts`, which serves Lucide from the bundled icon JSON so the build needs no Iconify API, and writes the ignored `public/demo.fig`, which the app opens like any `.fig` file; it is never generated in the browser. `ensureDemoDocument` runs from `vite.config.ts`, rebuilds only when its inputs' fingerprint changes, and runs the build in Bun; `bun run generate:demo` forces it. A chapter that needs something new from the engine adds that package's `src` to the fingerprint in `tools/generate/demo/src/ensure.ts`. Shader fills get their still frames from `src/shaders/stills.ts`, which draws each preset in the Playwright Chromium with WebGPU (`bunx playwright install chromium` locally; the deploy and preview workflows install it); without the browser the build warns and the editor draws the frames when the demo opens.+The `/demo` document is a tour of eight chapters on one page, each a section stacked top to bottom, built from `tools/generate/demo/src/document/`: `theme.ts` (the Theme and App chrome collections, each with a Dark and a Light mode that `src/app/demo/theme.ts` switches by name to follow the app's theme; every color in the tour, icons included, is bound to them), `callout.tsx` (the Tip component every chapter instances, whose Where slot each fills with a piece of the app from `chrome.tsx`, drawn to the dark theme's tokens with the target ringed), `player/` (the player card, its artwork slot, and its controls with behaviours), and one file per chapter under `chapters/`, laid out by `chapters/chapter.ts` as numeral, heading, subject, and tip, with each section's and subject's name from `chapters/names.ts`, which hosts outside the app such as the docs landing import from `@open-pencil/demo-tools/chapters`; `src/app/demo/viewport.ts` opens the tour on the first chapter. It renders design JSX through `document/icons.ts`, which serves Lucide from the bundled icon JSON so the build needs no Iconify API, and writes the ignored `public/demo.fig`, which the app opens like any `.fig` file; it is never generated in the browser. `ensureDemoDocument` runs from `vite.config.ts`, rebuilds only when its inputs' fingerprint changes, and runs the build in Bun; `bun run generate:demo` forces it. A chapter that needs something new from the engine adds that package's `src` to the fingerprint in `tools/generate/demo/src/ensure.ts`. Shader fills get their still frames from `src/shaders/stills.ts`, which draws each preset as WebP in the Playwright Chromium with WebGPU (`bunx playwright install chromium` locally; the deploy and preview workflows install it); without the browser the build warns and the editor draws the frames when the demo opens.## Brand assetsdiff --git a/tools/generate/demo/package.json b/tools/generate/demo/package.jsonindex c7792fd27..38c6ec986 100644--- a/tools/generate/demo/package.json+++ b/tools/generate/demo/package.json@@ -6,7 +6,8 @@"#demo/*": "./src/*.ts"},"exports": {- ".": "./src/ensure.ts"+ ".": "./src/ensure.ts",+ "./chapters": "./src/document/chapters/names.ts"},"scripts": {"test": "bun test tests"diff --git a/tools/generate/demo/src/document/chapters/chapter.ts b/tools/generate/demo/src/document/chapters/chapter.tsindex b7d413464..a8ad79645 100644--- a/tools/generate/demo/src/document/chapters/chapter.ts+++ b/tools/generate/demo/src/document/chapters/chapter.ts@@ -13,6 +13,7 @@ import { tipInstance, type Tip } from '../callout'import { renderTree } from '../icons'import { fillSlot } from '../slot-content'import type { Theme } from '../theme'+import { sectionName, type TourChapter } from './names'/** Where the first chapter sits on the page. */export const PAGE_ORIGIN = 0@@ -101,15 +102,16 @@ function heading({ vars }: Theme, index: number, { title, subtitle }: Heading):/*** Lay a chapter out in a section of its own: heading, then `subject` under it, then `tip` to- * the subject's right, top aligned. `fill` adds to the subject once it exists, before the tip- * is placed beside it, for content that needs the subject's layers, such as instances of a- * component in it. The section is left at the page origin; `arrangeChapters` places it.+ * the subject's right, top aligned. The section and the subject take their names from+ * `chapter`, which hosts outside the tour find them by. `fill` adds to the subject once it+ * exists, before the tip is placed beside it, for content that needs the subject's layers, such+ * as instances of a component in it. The section is left at the page origin; `arrangeChapters`+ * places it.*/export async function layoutChapter(context: ChapterContext,options: {- index: number- name: string+ chapter: TourChapterheading: Headingsubject: TreeNodetip: Tip@@ -117,10 +119,11 @@ export async function layoutChapter(}): Promise<Chapter> {const { graph, pageId } = context+ const { chapter } = optionsconst section = await place(context,Section({- name: `${options.index} · ${options.name}`,+ name: sectionName(chapter),w: 100,h: 100,bg: context.theme.vars.section@@ -132,13 +135,15 @@ export async function layoutChapter(const pad = CHAPTER_PADDINGconst head = await place(context,- heading(context.theme, options.index, options.heading),+ heading(context.theme, chapter.index, options.heading),section.id,pad,pad)const top = pad + head.height + HEADING_GAP- let subject = await place(context, options.subject, section.id, pad, top)+ const placed = await place(context, options.subject, section.id, pad, top)+ graph.updateNode(placed.id, { name: chapter.subject })+ let subject = graph.getNode(placed.id) ?? placedif (options.fill) {await options.fill(subject)computeAllLayouts(graph, pageId)diff --git a/tools/generate/demo/src/document/chapters/code.ts b/tools/generate/demo/src/document/chapters/code.tsindex 80f6e31ae..6c9b4aa4e 100644--- a/tools/generate/demo/src/document/chapters/code.ts+++ b/tools/generate/demo/src/document/chapters/code.ts@@ -2,13 +2,13 @@ import { Instance } from '@open-pencil/design-jsx'import { panelTabs } from '../chrome'import { layoutChapter, type Chapter, type ChapterContext } from './chapter'+import { CHAPTERS } from './names'import type { Player } from './slots'/** Code: the player once more, for the Code tab to read. */export function createCodeChapter(context: ChapterContext, player: Player): Promise<Chapter> {return layoutChapter(context, {- index: 6,- name: 'Code',+ chapter: CHAPTERS.code,heading: {title: 'It is code, too.',subtitle:diff --git a/tools/generate/demo/src/document/chapters/controls.ts b/tools/generate/demo/src/document/chapters/controls.tsindex 9e0ab30a1..8ba51db98 100644--- a/tools/generate/demo/src/document/chapters/controls.ts+++ b/tools/generate/demo/src/document/chapters/controls.ts@@ -5,6 +5,7 @@ import { previewPill } from '../chrome'import type { PlayerParts } from '../player/card'import { optionToggle, playToggle, progressSlider, skipButton } from '../player/controls'import { layoutChapter, type ChapterContext } from './chapter'+import { CHAPTERS } from './names'/** The variant of the set `setId` named `name`. */export function variantOf(graph: SceneGraph, setId: string, name: string): string {@@ -20,15 +21,13 @@ export function variantOf(graph: SceneGraph, setId: string, name: string): strinexport async function createControlsChapter(context: ChapterContext): Promise<PlayerParts> {const { graph, theme } = contextconst { subject: board } = await layoutChapter(context, {- index: 3,- name: 'Controls',+ chapter: CHAPTERS.controls,heading: {title: 'They work.',subtitle:'Each main component has a behaviour from the panel: a slider, two toggles, a button. In preview they run as real Reka UI controls, drawn by their own variants.'},subject: Frame({- name: 'Controls',flex: 'col',w: 'hug',h: 'hug',diff --git a/tools/generate/demo/src/document/chapters/hello.ts b/tools/generate/demo/src/document/chapters/hello.tsindex fb8da079a..ff0722fb9 100644--- a/tools/generate/demo/src/document/chapters/hello.ts+++ b/tools/generate/demo/src/document/chapters/hello.ts@@ -3,6 +3,7 @@ import type { ShaderPreset } from '@open-pencil/scene-graph'import { previewButton } from '../chrome'import { layoutChapter, type Chapter, type ChapterContext } from './chapter'+import { CHAPTERS } from './names'import type { Player } from './slots'export const HERO_WIDTH = 880@@ -31,15 +32,13 @@ export const HERO_PRESET: ShaderPreset = {/** Hello: the player on a live background, and the one thing to try first. */export function createHelloChapter(context: ChapterContext, player: Player): Promise<Chapter> {return layoutChapter(context, {- index: 1,- name: 'Hello',+ chapter: CHAPTERS.hello,heading: {title: 'Hello.',subtitle:'This file is a short tour. Scroll down, or drag the canvas with the hand tool, to follow it: every chapter shows one thing and a card tells you what to try. Nothing here is a mock-up: it is all editable.'},subject: Frame({- name: 'Hero',flex: 'row',w: HERO_WIDTH,h: HERO_HEIGHT,diff --git a/tools/generate/demo/src/document/chapters/lint.ts b/tools/generate/demo/src/document/chapters/lint.tsindex af6c85417..fc4197969 100644--- a/tools/generate/demo/src/document/chapters/lint.ts+++ b/tools/generate/demo/src/document/chapters/lint.ts@@ -2,20 +2,19 @@ import { Frame, Text } from '@open-pencil/design-jsx'import { panelTabs } from '../chrome'import { layoutChapter, type Chapter, type ChapterContext } from './chapter'+import { CHAPTERS } from './names'/** Lint: a card with issues planted in it, for the Lint tab to find. */export function createLintChapter(context: ChapterContext): Promise<Chapter> {const { vars } = context.themereturn layoutChapter(context, {- index: 7,- name: 'Lint',+ chapter: CHAPTERS.lint,heading: {title: 'It checks itself.',subtitle:'Lint reads the document the way a reviewer would: contrast, touch targets, layer names, spacing, colors that bypass the variables. The same rules run from the CLI, so a CI job can fail on them.'},subject: Frame({- name: 'Sign-in',flex: 'col',w: 360,h: 'hug',diff --git a/tools/generate/demo/src/document/chapters/modes.ts b/tools/generate/demo/src/document/chapters/modes.tsindex ed4eb647c..ff77b14de 100644--- a/tools/generate/demo/src/document/chapters/modes.ts+++ b/tools/generate/demo/src/document/chapters/modes.ts@@ -2,6 +2,7 @@ import { Frame, Instance } from '@open-pencil/design-jsx'import { variablesRow } from '../chrome'import { layoutChapter, type Chapter, type ChapterContext } from './chapter'+import { CHAPTERS } from './names'import type { Player } from './slots'/** Modes: the same player twice, each frame reading the Theme collection in its own mode. */@@ -22,15 +23,13 @@ export async function createModesChapter(children: [Instance({ of: player.id })]})const chapter = await layoutChapter(context, {- index: 4,- name: 'Modes',+ chapter: CHAPTERS.modes,heading: {title: 'It has modes.',subtitle:'Every color and radius in the player is a variable from one Theme collection. Each frame reads it in its own mode; nothing else differs. The rest of the tour follows the app’s theme the same way.'},subject: Frame({- name: 'Modes',flex: 'row',w: 'hug',h: 'hug',diff --git a/tools/generate/demo/src/document/chapters/names.ts b/tools/generate/demo/src/document/chapters/names.tsnew file mode 100644index 000000000..115440dc7--- /dev/null+++ b/tools/generate/demo/src/document/chapters/names.ts@@ -0,0 +1,28 @@+/**+ * The tour's chapters in reading order: the number and name its section shows, and the name of+ * its subject, the layer the chapter is about. Hosts that show one chapter, such as the docs+ * landing, find it by these names; `tests/build.test.ts` holds the document to them.+ */+export const CHAPTERS = {+ hello: { index: 1, name: 'Hello', subject: 'Hero' },+ slots: { index: 2, name: 'Slots', subject: 'Players' },+ controls: { index: 3, name: 'Controls', subject: 'Controls' },+ modes: { index: 4, name: 'Modes', subject: 'Modes' },+ shaders: { index: 5, name: 'Shaders', subject: 'Shaders' },+ code: { index: 6, name: 'Code', subject: 'Player' },+ lint: { index: 7, name: 'Lint', subject: 'Sign-in' },+ yours: { index: 8, name: 'Yours', subject: 'Ways' }+} as const satisfies Record<string, TourChapter>++export interface TourChapter {+ index: number+ name: string+ subject: string+}++export type ChapterKey = keyof typeof CHAPTERS++/** The chapter's section name, as the layer list shows it. */+export function sectionName({ index, name }: TourChapter): string {+ return `${index} · ${name}`+}diff --git a/tools/generate/demo/src/document/chapters/shaders.ts b/tools/generate/demo/src/document/chapters/shaders.tsindex 18010f17b..26f04ab87 100644--- a/tools/generate/demo/src/document/chapters/shaders.ts+++ b/tools/generate/demo/src/document/chapters/shaders.ts@@ -6,6 +6,7 @@ import { fillRow } from '../chrome'import { COVER_PRESET } from '../player/card'import type { Theme } from '../theme'import { layoutChapter, type Chapter, type ChapterContext } from './chapter'+import { CHAPTERS } from './names'const TILE = 320@@ -50,15 +51,13 @@ function tile({ vars }: Theme, { name, preset }: (typeof PRESETS)[number]): Tree/** Shaders: a fill that moves, on plain rectangles, with its preset editable in the fill picker. */export function createShadersChapter(context: ChapterContext): Promise<Chapter> {return layoutChapter(context, {- index: 5,- name: 'Shaders',+ chapter: CHAPTERS.shaders,heading: {title: 'Fills can move.',subtitle:'A shader is a fill like any other: pick it in the fill picker, stack effects, tune their sliders, or paste a preset from shaders.com. Files keep a still of it, and preview plays it.'},subject: Frame({- name: 'Shaders',flex: 'row',w: 'hug',h: 'hug',diff --git a/tools/generate/demo/src/document/chapters/slots.ts b/tools/generate/demo/src/document/chapters/slots.tsindex f15eb8e34..2e39e1dfe 100644--- a/tools/generate/demo/src/document/chapters/slots.ts+++ b/tools/generate/demo/src/document/chapters/slots.ts@@ -13,6 +13,7 @@ import { ARTWORK_NAME, PLAYER_PROPERTIES, playerComponent, type PlayerParts } frimport { fillSlot } from '../slot-content'import type { Theme } from '../theme'import { layoutChapter, type ChapterContext } from './chapter'+import { CHAPTERS } from './names'export interface Player {/** The Player main component. */@@ -78,15 +79,13 @@ export async function createSlotsChapter(const { graph, theme } = contextconst player: Player = { id: '', slotId: createComponentPropertyId() }await layoutChapter(context, {- index: 2,- name: 'Slots',+ chapter: CHAPTERS.slots,heading: {title: 'It is a component.',subtitle:'The player on the left is the main component. Its artwork is a slot: every instance keeps the player and brings its own cover.'},subject: Frame({- name: 'Players',flex: 'row',w: 'hug',h: 'hug',diff --git a/tools/generate/demo/src/document/chapters/yours.ts b/tools/generate/demo/src/document/chapters/yours.tsindex f4d3c1f6e..f61b51549 100644--- a/tools/generate/demo/src/document/chapters/yours.ts+++ b/tools/generate/demo/src/document/chapters/yours.ts@@ -11,6 +11,7 @@ import {type Chapter,type ChapterContext} from './chapter'+import { CHAPTERS } from './names'const TIP_COMPONENT_GAP = 96@@ -83,15 +84,13 @@ function way({ vars }: Theme, { icon, title, body }: (typeof WAYS)[number]): Treexport async function createYoursChapter(context: ChapterContext): Promise<Chapter> {const { graph, theme } = contextconst chapter = await layoutChapter(context, {- index: 8,- name: 'Yours',+ chapter: CHAPTERS.yours,heading: {title: 'Now make it yours.',subtitle:'The tour ends here. The document does not: everything in it is yours to edit, and it works with what you already have.'},subject: Frame({- name: 'Ways',flex: 'col',w: 640,h: 'hug',diff --git a/tools/generate/demo/tests/build.test.ts b/tools/generate/demo/tests/build.test.tsindex b911818a7..df5b36d28 100644--- a/tools/generate/demo/tests/build.test.ts+++ b/tools/generate/demo/tests/build.test.ts@@ -1,6 +1,7 @@import { beforeAll, describe, expect, test } from 'bun:test'import { buildDemoGraph, measuringRenderer } from '#demo/build'+import { CHAPTERS, sectionName } from '#demo/document/chapters/names'import { exportFigFile, readFigFile } from '@open-pencil/core/io'import { populateAllFigPages } from '@open-pencil/core/io/formats/fig'@@ -61,18 +62,21 @@ describe('the demo document', () => {.getChildren(page.id).filter((node) => node.type === 'SECTION').sort((a, b) => a.y - b.y)- expect(chapters.map((chapter) => chapter.name)).toEqual([- '1 · Hello',- '2 · Slots',- '3 · Controls',- '4 · Modes',- '5 · Shaders',- '6 · Code',- '7 · Lint',- '8 · Yours'- ])+ expect(chapters.map((chapter) => chapter.name)).toEqual(+ Object.values(CHAPTERS).map(sectionName)+ )// The layer list reads the first child first.- expect(graph.getChildren(page.id)[0]?.name).toBe('1 · Hello')+ expect(graph.getChildren(page.id)[0]?.name).toBe(sectionName(CHAPTERS.hello))+ })++ test("names each chapter's subject as hosts look it up", () => {+ const [page] = graph.getPages()+ const sections = graph.getChildren(page.id)+ for (const chapter of Object.values(CHAPTERS)) {+ const section = sections.find((node) => node.name === sectionName(chapter))+ const children = section ? graph.getChildren(section.id) : []+ expect(children.filter((child) => child.name === chapter.subject)).toHaveLength(1)+ }})test('keeps complete behaviours on the player controls', () => {