@heycys/gallery 0.0.0-stage → 0.1.0

package/sdk/column-widths.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The types of the table column allocator (`DocTables.allocateColumnWidths`), kept here so that the
+ * SDK stands alone: the kit's own code takes them from this file.
+ */
+export type ColumnKind = 'compact' | 'narrative' | 'token-heavy';
+export interface ColumnInput {
+  key: string;
+  header: string;
+  cells: Array<string | number | null | undefined>;
+  kind?: ColumnKind;
+  minWidth?: number;
+  maxWidth?: number;
+  /** A column of numbers (the kit's numeric columns): its readable floor is never lowered by maxReadableFloor. */
+  numeric?: boolean;
+  /** Optional measured header width including padding/controls; supplied by the DOM adapter. */
+  headerWidth?: number;
+  /** Optional unwrapped widths including padding, aligned with cells; supplied by the DOM adapter. */
+  cellWidths?: number[];
+  /** Optional widths of the header's and each cell's longest word (WORD_BREAKS) including padding; supplied by the DOM adapter. */
+  headerWordWidth?: number;
+  cellWordWidths?: number[];
+  /** Optional widths of each cell's widest piece no line breaks in (PIECE_BREAKS, a number range) including padding; supplied by the DOM adapter. */
+  cellPieceWidths?: number[];
+}
+export interface ColumnLayout {
+  key: string;
+  kind: ColumnKind;
+  preferredWidth: number;
+  /** Readable floor: when their sum exceeds the viewport, scroll instead of compressing further. */
+  softMinWidth: number;
+  hardMinWidth: number;
+  width: number;
+  /** Relative to the allocated columns, which may exceed totalWidth at their readable floors. */
+  ratio: number;
+}
+export interface ColumnWidthOptions {
+  /** Available table width, including cell padding. */
+  totalWidth: number;
+  percentile?: number;
+  hardMinWidth?: number;
+  narrativeMinWidth?: number;
+  /**
+   * The most a column's readable floor may be, whatever its kind (a prose column's baseline and its
+   * three lines of P90 text, a path's, a short field's protected width alike), but a numeric
+   * column's; unset, no limit. On a narrow screen the kit passes a third of the table's room, so that
+   * a table of two or three columns wraps their text before it scrolls sideways.
+   */
+  maxReadableFloor?: number;
+  tokenHeavyMinWidth?: number;
+  compactMaxProtectedWidth?: number;
+  cellPadding?: number;
+  columnOverhead?: number;
+  font?: string;
+}
+/** Column widths from the cells' text: deterministic P90 + water filling, with scrolling at readable floors. */
+export type AllocateColumnWidths = (columns: ColumnInput[], options: ColumnWidthOptions) => ColumnLayout[];

package/sdk/doc-charts.d.ts

@@ -0,0 +1,82 @@
+/**
+ * A cell of a table a chart is drawn from: null for an empty or missing cell, a dash or n/a; a number
+ * when it writes one number (12.5%, 3.6亿, 约 20; its data-sort-value first); else its words (a range,
+ * 3 / 4, a column whose header has data-sort-type "text" or "date"). references/writing-html.md says it in full.
+ */
+export type DocTableValue = number | string | null;
+
+/** A row of that table: each value by its column's header words. */
+export type DocTableRow = Record<string, DocTableValue>;
+
+/**
+ * The rows a chart drawn from a table (`data-doc-chart-data`) gets as `data`: its body rows in the
+ * file's order (<tfoot> left out), and its header's words in order (`columns`, as d3.csvParse gives).
+ */
+export interface DocTableRows extends Array<DocTableRow> {
+  columns: string[];
+}
+
+/** What a document's own chart type draws with (see `DocChartsApi.define`). */
+export interface DocChartDrawContext<Data = any> {
+  /** The declared chart's host, emptied before each call (its data script stays). */
+  host: HTMLElement;
+  /** The declared JSON of this chart; for a chart drawn from a table (data-doc-chart-data), its rows (DocTableRows). */
+  data: Data;
+  /** Colors of the current theme. */
+  tokens: import("./doc-tokens.js").DocTokenSnapshot;
+  /** The host's width in px. */
+  width: number;
+  /** The card's plot height in px when it sets one (`--doc-chart-height`, e.g. from the preview); otherwise null. */
+  height: number | null;
+}
+
+/** A chart of a document's own type. */
+export interface DocDrawnChartHandle<Data = any> {
+  /** Draw again, with new data if given (a chart drawn from a table takes none: it draws its table). */
+  redraw(nextData?: Data): void;
+  destroy(): void;
+}
+
+/** What a part of a document's own type is started with: the drawing context and its lifetime. */
+export interface DocChartPartContext<Data = any> extends DocChartDrawContext<Data> {
+  /** Aborted when the part is destroyed (its host left the page): give it to addEventListener. */
+  signal: AbortSignal;
+}
+
+/**
+ * A part of a document's own type: something that keeps what it needs (listeners, timers, an
+ * animation) between drawings. `mount` starts it in the emptied host; `update` is called when its
+ * width, the theme or its card's height change (or a script redraws it, or the rows of its table
+ * change), `destroy` when its host leaves the page.
+ */
+export interface DocChartPart<Data = any> {
+  mount(context: DocChartPartContext<Data>): { update?(context: DocChartPartContext<Data>): void; destroy?(): void } | void;
+}
+
+/**
+ * Charts are declared in their cards, each of a type the document's script defines:
+ * `<div data-doc-chart="slope"><script type="application/json">…its data…</script></div>`, or
+ * `<div data-doc-chart="slope" data-doc-chart-data="t1"></div>`, drawn from the rows of the table
+ * whose frame carries `data-doc-chart-source="t1"`.
+ */
+export interface DocChartsApi {
+  /**
+   * Define a chart type of the document's own, drawn from the data of each chart declared with it
+   * (its JSON, or its table's rows: DocTableRows). `type` is lowercase letters, digits and hyphens,
+   * a letter first (`interval`, `ci-plot`). `draw` is called again when a chart's width, the theme
+   * or its card's height change, and when its table's rows do; a part (`{ mount }`) keeps what it
+   * starts until its host leaves the page.
+   */
+  define<Data = any>(type: string, draw: ((context: DocChartDrawContext<Data>) => void) | DocChartPart<Data>): void;
+  /** The chart drawn in a host; null if none. */
+  get(target: string | Element): DocDrawnChartHandle | null;
+}
+
+declare global {
+  /** The rows a chart drawn from a table gets as `data`, for a document's script to type it with (JSDoc's `@type {DocTableRows}`). */
+  type DocTableRows = import("./doc-charts.js").DocTableRows;
+  /** A row of a table a chart is drawn from. */
+  type DocTableRow = import("./doc-charts.js").DocTableRow;
+  /** A cell's value of a table a chart is drawn from. */
+  type DocTableValue = import("./doc-charts.js").DocTableValue;
+}

package/sdk/doc-code.d.ts

@@ -0,0 +1,28 @@
+// Code blocks are <div class="doc-code"> holding their title and a <pre><code> (highlighted on
+// their own); a diff is declared as <div class="doc-diff"> holding its title and these options as
+// JSON, its header showing the lines added and removed.
+export interface CodeViewOptions {
+  code: string;
+  /** Overrides path inference; unknown languages render as plain text. */
+  language?: string;
+  path?: string;
+  /** Default true. Copying excludes the gutter. */
+  showLineNumbers?: boolean;
+}
+export interface DiffLineData {
+  type: 'added' | 'removed' | 'unchanged';
+  content: string;
+  /** Optional positive integer; omitted numbers leave a blank gutter. */
+  lineNumber?: number;
+}
+export interface DiffViewOptions extends Omit<CodeViewOptions, 'code'> {
+  lines: DiffLineData[];
+  /** Default true. */
+  coloredLineNumbers?: boolean;
+  /** Default true. */
+  showAccentStrip?: boolean;
+}
+declare global {
+  /** gallery check's alone (no such function on the page): a declared diff's JSON (`<div class="doc-diff">`) as its options. */
+  function __declaredDiff(options: DiffViewOptions): void;
+}

package/sdk/doc-dialogs.d.ts

@@ -0,0 +1,4 @@
+export interface DocDialogsApi {
+  open(target: string | HTMLDialogElement, opener?: HTMLElement | null): HTMLDialogElement;
+  close(target: string | HTMLDialogElement, returnValue?: string): HTMLDialogElement;
+}

package/sdk/doc-kit.d.ts

@@ -0,0 +1,141 @@
+import type { DocState } from "./doc-state.js";
+
+/**
+ * What an instance can hear (`on`). `editable`: `context.canEdit()` has just become true, for one mounted before the page came to edit.
+ * `content`: a change inside the instance, heard only with `owns: false`, as what a component owns the
+ * kit does not watch; a change of what the file says of it is `source`, whatever it owns.
+ */
+export type DocComponentSignal = "source" | "resize" | "theme" | "layout" | "viewport" | "fonts" | "content" | "reveal" | "editable";
+
+/** What a component's `mount` returns, all of it optional. */
+export interface DocComponentHandle {
+  /**
+   * A signal it asked for (`on`). `detail`: the mutation records of `source` and `content`; the faces of a
+   * later `fonts`. `options.quiet`: on `content`, a change that leaves the page looking as it was.
+   */
+  update?(reason: DocComponentSignal, detail?: unknown, options?: { quiet?: boolean }): void;
+  /** The host left the page. What listens on `context.signal` goes by itself. */
+  destroy?(): void;
+}
+
+export interface DocComponentStateOptions<T extends Record<string, unknown>> {
+  /** Positive integer. A state of another version, or defaults of another shape, under this instance's name throws: see `DocStateFactory.getOrCreate`. */
+  version: number;
+  /** JSON-serializable default state. */
+  defaults: T;
+  /** Default: []; excluded from browser restoration and exported snapshots. */
+  transientKeys?: Array<keyof T & string>;
+}
+
+/** What `mount` is given for a package's instance. */
+export interface DocComponentContext {
+  /** The instance's element. */
+  readonly host: HTMLElement;
+  /** Aborts when the instance ends: give it to what the component listens to. */
+  readonly signal: AbortSignal;
+  /**
+   * Run `draw` in the frame the kit draws in, once: of what is asked before that frame, the last `draw`
+   * runs. Asked from inside a `draw` it runs in the next frame; a chain of those is an animation, which
+   * the page does not wait for to count as drawn. Nothing runs once the instance has failed.
+   */
+  frame(draw: () => void): void;
+  /** Say this instance failed: it ends there, even as `mount` runs, and shows what it holds, read-only. */
+  fail(error: unknown): void;
+  /** The first element of a part of the manifest, or null. A name the manifest does not have throws. */
+  part(name: string): HTMLElement | null;
+  /** This instance's reading state, of no other instance of the package: the same object at every mount. */
+  state<T extends Record<string, unknown>>(options: DocComponentStateOptions<T>): DocState<T>;
+  /**
+   * Whether `edit` writes to the file now. False until the page comes to edit (the `editable` signal
+   * says when, for one that asked), and for good in an exported file and its PDF, in 演示视图, for an
+   * instance that failed and for one whose `data-doc-schema` is past its manifest's `schema`.
+   */
+  canEdit(): boolean;
+  /**
+   * Change a part edited as data, whose name its manifest gives: `change` is handed a draft of the part
+   * (its first element, off the page) and changes what it holds, at once. Returns whether that was taken:
+   * then it stands on the page, one undo step, and the file follows by itself, as for any edit. False
+   * while `canEdit()` is false, and where `change` throws, writes the part on the page instead of the
+   * draft, or leaves what a file cannot hold (a script, a handler, an element that does not read back as
+   * itself, its own tag changed): nothing has happened then, and the console says why. Undo puts the
+   * part back and `source` tells you, like any change of it. A name the manifest does not have, or a
+   * part not edited as data, throws. A list of names changes those parts in one write, one undo step (a
+   * gesture that moves a card and counts the move): `change` is handed a draft of each, by its name, and
+   * two that are one element, or one in the other, throw.
+   */
+  edit<P extends string | string[]>(part: P, change: (draft: P extends string[] ? Record<string, HTMLElement> : HTMLElement) => void): boolean;
+}
+
+/** What a package's kit.js registers. */
+export interface DocComponent {
+  /** The package's id, as its manifest writes it: <scope>/<name>. */
+  id: string;
+  /** The signals `update` is to hear. */
+  on?: DocComponentSignal[];
+  /** Default: true. The kit watches nothing the component draws in its instance, but what its parts edit as text or data. */
+  owns?: boolean;
+  /**
+   * Starts an instance, a thrown error or a promise rejected being that instance's failure alone: it
+   * shows what it holds, read-only, and the page goes on. Called again on a node an undo puts back and
+   * in an exported file: the kit takes off `dehydrate`'s and the manifest's `runtime`'s first.
+   */
+  mount(host: HTMLElement, context: DocComponentContext): DocComponentHandle | void | Promise<DocComponentHandle | void>;
+  /**
+   * Takes off of `host` what `mount` left and the manifest's `runtime` does not name. It may be given a
+   * host with none of it: an error it throws is told on the console, and `mount` goes on.
+   */
+  dehydrate?(host: HTMLElement): void;
+  /**
+   * A small edit, as a reader's gesture would make it, by `context.edit`: what `gallery component check`
+   * calls to try the way back to the file. Nothing else calls it.
+   */
+  example?(host: HTMLElement, context: DocComponentContext): void;
+}
+
+declare global {
+  /** What `mount` is given, for a package's kit.js to name it with (JSDoc's `@param {DocComponentContext} context`), with no import. */
+  type DocComponentContext = import("./doc-kit.js").DocComponentContext;
+  /** What `mount` returns. */
+  type DocComponentHandle = import("./doc-kit.js").DocComponentHandle;
+  /** A signal `update` hears. */
+  type DocComponentSignal = import("./doc-kit.js").DocComponentSignal;
+  /** What kit.js registers. */
+  type DocComponent = import("./doc-kit.js").DocComponent;
+}
+
+/** How much the kit runs now. */
+export interface DocKitStats {
+  /** Instances alive, by component. */
+  live: Record<string, number>;
+  mounted: number;
+  destroyed: number;
+  failed: number;
+  components: string[];
+}
+
+/** The kit's runtime: every component instance on the page. */
+export interface DocKitApi {
+  /** Register a component. An id registered already throws. */
+  component(definition: DocComponent): unknown;
+  /** What Gallery says of a package; generated, never written by hand. */
+  describe(description: { id: string; [field: string]: unknown }): void;
+  /** What is known of a component: where its instances are and its parts, or null. */
+  description(id: string): { id: string; [field: string]: unknown } | null;
+  /** Start what `root` holds now, as if it had been added. */
+  mount(root?: ParentNode): void;
+  /** End the instance on `host`. */
+  destroy(host: Element): void;
+  /** Run a change that leaves the page looking as it was. */
+  quietly<T>(change: () => T): T;
+  /** Take what the kit and its components left off `root`, a copy of the page. */
+  dehydrate<T extends Element>(root: T): T;
+  /** The component on `host` makes its `example` of an edit, as `gallery component check` asks it. Whether it has one. */
+  example(host: Element): boolean;
+  /** Open what hides an element, and bring it into view. */
+  reveal(element: Element): void;
+  stats(): DocKitStats;
+  /** The keys of the page's bound controls. */
+  readonly bindings: unknown;
+  /** The selectors of the elements blocks stand in. */
+  readonly flows: readonly string[];
+}

package/sdk/doc-math.d.ts

@@ -0,0 +1,3 @@
+export interface DocMathApi {
+  render(root?: ParentNode): void;
+}

package/sdk/doc-sheets.d.ts

@@ -0,0 +1,15 @@
+/** A Sheet area: the tab it shows. */
+export interface DocSheetsHandle {
+  get(): string;
+  set(tab: string): void;
+  destroy(): void;
+}
+
+/**
+ * Sheet areas start on their own (`<section class="doc-sheet-shell" data-doc-sheets="name">`,
+ * its tab kept under its name); a script may ask one which tab it shows, or show another.
+ */
+export interface DocSheetsApi {
+  /** The area a selector or element finds; null before it has started. */
+  get(target: string | Element): DocSheetsHandle | null;
+}

package/sdk/doc-state.d.ts

@@ -0,0 +1,41 @@
+export type DocStateChange =
+  | { type: "set"; key: string }
+  | { type: "update"; keys: string[] }
+  | { type: "reset" }
+  | { type: "hydrate" };
+
+export interface DocState<T extends Record<string, unknown> = Record<string, unknown>> {
+  readonly id: string;
+  readonly version: number;
+  get<K extends keyof T>(key: K, fallback?: T[K]): T[K];
+  snapshot(): T;
+  set<K extends keyof T>(key: K, value: T[K]): void;
+  update(values: Partial<T>): void;
+  /** Restore defaults and save them, so an older embedded snapshot cannot reappear. */
+  reset(): void;
+  subscribe(listener: (snapshot: T, change: DocStateChange) => void): () => void;
+  serialize(): string;
+  hydrate(serialized: string): void;
+}
+
+export interface DocStateOptions<T extends Record<string, unknown>> {
+  /** The state's name within this document, such as "view". Storage is kept per document (its data-doc-id), so "view" and "<slug>:view" name the same state. */
+  id: string;
+  /** Positive integer checked against stored/embedded snapshots. */
+  version: number;
+  /** JSON-serializable default state; reuse one instance per id/version. */
+  defaults: T;
+  /** Overrides the browser storage key; normally left out. */
+  storageKey?: string;
+  /** Default: []; excluded from browser restoration and exported snapshots. */
+  transientKeys?: Array<keyof T & string>;
+}
+
+export interface DocStateFactory {
+  readonly schemaVersion: 1;
+  /** Throws when the state exists already: one id and version is one state. */
+  create<T extends Record<string, unknown>>(options: DocStateOptions<T>): DocState<T>;
+  /** The state of this id: the one made already when its version and the shape of its defaults are these, a new one when there is none, and an error otherwise. */
+  getOrCreate<T extends Record<string, unknown>>(options: DocStateOptions<T>): DocState<T>;
+  serializeAll(): string;
+}

package/sdk/doc-tables.d.ts

@@ -0,0 +1,24 @@
+import type { AllocateColumnWidths, ColumnLayout } from "./column-widths.js";
+export type { AllocateColumnWidths, ColumnInput, ColumnKind, ColumnLayout, ColumnWidthOptions } from "./column-widths.js";
+export type DocSortDirection = "asc" | "desc";
+export type DocSortType = "number" | "text" | "date";
+
+export interface DocTableSortDetail {
+  column: number;
+  key: string | null;
+  direction: DocSortDirection;
+}
+
+export interface DocTableState {
+  /** null restores original row order. */
+  sort: { column: number; direction: DocSortDirection; key?: string | null } | null;
+}
+
+export interface DocTablesApi {
+  allocateColumnWidths: AllocateColumnWidths;
+  /** Remeasure a table now. Hidden tables wait until visible; returns the last layout or []. */
+  layout(target: string | HTMLTableElement): ColumnLayout[];
+  getState(target: string | HTMLTableElement): DocTableState;
+  setState(target: string | HTMLTableElement, state: DocTableState): void;
+  subscribe(target: string | HTMLTableElement, listener: (state: DocTableState) => void): () => void;
+}

package/sdk/doc-tokens.d.ts

@@ -0,0 +1,22 @@
+export interface DocTokenSnapshot {
+  readonly tone: (name: "success" | "danger" | "warning" | "info" | "neutral" | "accent" | "muted" | "text" | "border") => string;
+  readonly css: (name: string, fallback?: string) => string;
+  readonly bg: string;
+  readonly surface: string;
+  readonly text: string;
+  readonly muted: string;
+  readonly border: string;
+  readonly grid: string;
+  readonly accent: string;
+  readonly accentSoft: string;
+  readonly success: string;
+  readonly warning: string;
+  readonly danger: string;
+  readonly series: readonly string[];
+}
+
+export interface DocTokensApi {
+  readonly read: (element?: Element) => DocTokenSnapshot;
+  readonly seriesNames: readonly string[];
+}
+

package/sdk/index.d.ts

@@ -0,0 +1,30 @@
+import type { DocChartsApi } from "./doc-charts.js";
+import type { DocDialogsApi } from "./doc-dialogs.js";
+import type { DocKitApi } from "./doc-kit.js";
+import type { DocMathApi } from "./doc-math.js";
+import type { DocStateFactory } from "./doc-state.js";
+import type { DocSheetsApi } from "./doc-sheets.js";
+import type { DocTablesApi } from "./doc-tables.js";
+import type { DocTokensApi } from "./doc-tokens.js";
+
+declare global {
+  var DocCharts: DocChartsApi;
+  var DocDialogs: DocDialogsApi;
+  var DocKit: DocKitApi;
+  var DocMath: DocMathApi;
+  var DocState: DocStateFactory;
+  var DocSheets: DocSheetsApi;
+  var DocTables: DocTablesApi;
+  var DocTokens: DocTokensApi;
+}
+
+export * from "./doc-charts.js";
+export * from "./doc-dialogs.js";
+export * from "./doc-kit.js";
+export * from "./doc-math.js";
+export * from "./doc-state.js";
+export * from "./doc-sheets.js";
+export * from "./doc-tables.js";
+export * from "./doc-tokens.js";
+
+export * from "./doc-code.js";

package/skill/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: gallery
+description: "Gallery: turn supplied materials into a polished, interactive HTML document whose claims and numbers trace back to them (experiment and project write-ups, research findings, meeting summaries, explainers, comparisons), with charts, tables and formulas where they help. The user edits it in the browser as you write it and gets one offline HTML file. Use when the user asks for Gallery (or $gallery); not for general front-end development."
+---
+
+# Gallery
+
+Create a self-contained HTML document whose claims, numbers, and visual encodings can be traced back to the supplied materials. You write it as an ordinary web page. Gallery's command, `gallery`, turns it into the kit's blocks, checks it and exports it as one offline file; meanwhile the user can watch and edit it in the browser.
+
+## Before anything: the gallery command
+
+This skill holds the instructions; the tools are the npm package `@heycys/gallery`, the `gallery` command. This skill needs `@heycys/gallery` ^0.1.0: a version npm's range `^0.1.0` takes, 0.1.0 or a later 0.1.x.
+
+1. Run `gallery --version`. When it prints such a version, go on to step 3.
+2. When `gallery` is not found, or prints a version older than `^0.1.0` takes, install it with `npm i -g @heycys/gallery@^0.1.0`, then run `gallery --version` again. When the user has already said to install it (in this request or earlier in the conversation), run it without asking again; otherwise ask the user before you install anything: say that Gallery's command is missing (or which version it is) and that you would run that command, and run it once they agree.
+   - When it prints a version newer than `^0.1.0` takes, install nothing (that would take Gallery back to an older version): tell the user this skill is older than their Gallery and ask them to run `gallery skill install` (with `--project` when the skill is the project's, in its `.claude/skills/`), then to start a new Agent session, which reads the new skill.
+   - No Node, or `node --version` older than 22.13: tell the user to install the current LTS from https://nodejs.org (or with their system's package manager), then start again.
+   - npm says `EACCES` (macOS and Linux, where npm's global folder belongs to the system): never use `sudo`. Tell the user, and offer either of these: give npm a folder of their own (`npm config set prefix ~/.npm-global`, add `~/.npm-global/bin` to `PATH` in their shell profile, open a new terminal, install again); or run every command as `npx -y @heycys/gallery@^0.1.0 <command> …` instead of `gallery <command> …`.
+   - Use `npx -y @heycys/gallery@^0.1.0 <command> …` likewise wherever a global install is not allowed (a sandbox, CI). It is slower: a few seconds more per command.
+   - On Windows, `gallery` works in PowerShell right after the install, in the same terminal. Only when PowerShell says running scripts is disabled (`gallery.ps1`): run `gallery.cmd` with the same arguments, or ask the user to run `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` once.
+   - After an upgrade, run `gallery open --no-browser` once: the server of the version before stops by itself, and this starts the new one. Tell the user that `gallery skill install` brings this skill to the new version too (an Agent session started after it reads it).
+3. The documents live in a workspace, a folder: `--workspace <dir>` (every command takes it), else `GALLERY_WORKSPACE`, else the nearest folder up from the current one holding `gallery.json`, else `Gallery` in the user's Documents folder, `~/Documents/Gallery` (made on first use; on Windows the Documents folder Explorer shows, OneDrive's when OneDrive backs it up). `gallery new`, `gallery import`, `gallery list` and `gallery open` print it as `工作区：<path>`. When a command prints `Cannot write the workspace <path> (…)` (a sandbox that allows writes only in the project, or a system that has not let the terminal into Documents), ask the user to allow Gallery to write there, or pass `--workspace <a folder in the project>` to every command.
+4. The browser service: `gallery new` and `gallery import` start the workspace's local server (or use the one running) and open the user's browser at the document, `gallery open [<slug>]` starts or reuses it and opens the user's browser (each takes `--no-browser`: the address without a tab), and each prints the address on its `交给用户` line: give it to the user all the same (the browser opened may not be Chrome or Edge, or not in front of them). Editing in the browser and `gallery qa` need Chrome or Edge. In a cloud sandbox the user cannot reach (`127.0.0.1` there is not their computer), skip the address: hand over the exported file instead. `gallery stop` stops the server (`Stopped the server on port …`, or `No Gallery server runs for <workspace>.`).
+5. Every command but `gallery serve` returns by itself, the server's included (it runs on after the command; `gallery serve` runs it in the foreground, for the user's own terminal: you start it with `gallery open --no-browser`): run each in the foreground, with no `timeout` wrapper, background job or `Start-Process`. When you ask the user to allow commands, `gallery *` covers them all (`gallery.cmd *` in PowerShell). In Windows PowerShell 5.1, give a command no `2>&1` (it makes its warnings errors) and read files with the file tool or `Get-Content -Encoding UTF8`. Resolve `references/` and `sdk/` from the folder holding this `SKILL.md`.
+
+**写作偏好** (`<workspace>/preferences.md`) holds the user's rules for writing a document: what to write and in what order, the opening summary, titles, fidelity to the materials, evidence and data. Read it before you write and follow it. When instructions differ, the user's request comes first, then 写作偏好, then this skill. Only the user changes 写作偏好: never edit it unless asked, and never write `"instructions": true` in a document's `doc.json` (it marks the page holding 写作偏好). Where 写作偏好 says `report.json`, a document made by Gallery 0.1 or later has `doc.json`; an older one keeps `report.json`.
+
+A document has one writer at a time: never let two Agents, or an Agent and a script, write the same `doc.html` at once. The user may edit it in the browser meanwhile; Gallery merges their edits with yours.
+
+A document is the folder `<workspace>/<slug>/`: `doc.html`, the page you write, and `doc.json`, its title and description. Documents link to each other by ordinary relative links between these files (`../<slug>/doc.html`: writing-html.md). A document made before Gallery 0.1 has `report.html` and `report.json` instead: write those (Gallery reads and writes them under their names; never rename them). Below, `doc.html` and `doc.json` stand for either.
+
+## Workflow
+
+1. Read 写作偏好 before anything else. When `<workspace>/preferences.md` is not there yet, `gallery new` (step 2) makes it from Gallery's defaults and prints its path (`gallery import` and `gallery list` print it too; `gallery open` does not): read it then, before you write. When `gallery new` prints `写作偏好：空`, the user emptied it: write from the request, this skill and the materials, and leave the file as it is.
+2. Create the document as soon as you know its title: `gallery new <slug> "<title>" "<description>"` (a lowercase kebab-case slug).
+   - It prints where it wrote, the workspace, the path of 写作偏好 and the next steps, starts the browser service (or uses the one running), and ends with its `交给用户` line: the address where the user watches and edits the document (step 3). The line before it, the page alone, is yours.
+   - If the server could not start, it says why; once that is fixed, `gallery open <slug>` starts it and prints the address.
+   - The page renders straight from `doc.html`, reloads on every save, notes failing checks at its bottom left, and lets the user edit the document in place ([Revising a document](#revising-a-document)).
+   - When 写作偏好 asks for another title or description than the ones you gave, change them (the `h1` in `doc.html`, the description in `doc.json`).
+   - When the material is a file to be turned into the document (Markdown, HTML, Word, PDF, CSV, EPUB, or a ZIP of pages), create it with `gallery import <file> [<slug> ["<title>"]]` instead (it says the same, and what of the file it could not bring, by line), then edit what it made.
+3. Now, before you read further, send the user the address from the `交给用户` line in a message of its own, in the user's language: they watch the document being written there. In a cloud sandbox they cannot reach, skip it.
+4. Write `<workspace>/<slug>/doc.html` as ordinary HTML, replacing the starter section.
+   - Read [references/example-report.html](references/example-report.html) first: a catalogue of every block once, each written the way the tools read it, its words saying what the block is; take the blocks you need. Then read [references/writing-html.md](references/writing-html.md), whole.
+   - Write so that the user watches the document grow: as soon as you can outline it, replace the starter section with its skeleton (the opening summary's place and each section's heading), then write it a section at a time, one edit each. The page shows each save; one write of the whole document at the end leaves the user looking at the starter page until then.
+   - Materials can be large: list a folder before you read in it, and read what the document needs; no `du` or glob over a whole disk or tree.
+   - Take numbers and conclusions from the materials themselves: a summary of them, a subagent's too, is a lead to check, not a source.
+   - The document's data stays in `doc.html`. Its pictures and files go right in `<workspace>/<slug>/assets/` (writing-html.md's [Pictures](references/writing-html.md#pictures) says how to name and size them). Raw inputs that should travel with it go in `<workspace>/<slug>/materials/`.
+5. Export, check and look:
+   - `gallery export <slug>` makes the plain HTML of `doc.html` the kit's markup, gives every block its `data-block-id`, checks the document and writes the deliverable `<workspace>/exports/<slug>.html` ([what its lines mean](#what-the-commands-print)).
+   - `gallery qa <slug>` exports first when needed, opens the export in Chrome or Edge at 1024, 736 and 360px (every disclosure, Sheet panel and detail card in turn), prints each failure and warning with its place in the document's file (`doc.html:<line>`, `report.html:<line>` in an older document), and pictures what it flags and, in a plain run, up to 12 blocks (what you changed first, then the cards; a `--blocks` run pictures every block it names) in the folder its `Pictures of this run in <path>` line names (a run with nothing to picture, no block changed and no card, says so in its verdict and names the `--tiles` run to make instead). Read its whole output (the verdict comes last, then the deliverable's line) and look at the pictures: `changed/` holds what you changed or moved; `cards/` the cards no look has pictured yet, your own drawings, charts and components first, tables last (not your edits); `blocks/` and `tiles/` what you ask for with `gallery qa <slug> --blocks a,b` or `--tiles` (the whole page, each panel and card). A picture shows all an element draws: a mark cut at its edge is cut on the page too.
+   - Open at least every picture of `flagged/` and of `changed/`, at each width, then those of `cards/` that show what you drew yourself (your charts, drawings and flowcharts); open the rest as the document needs. In the handoff name the pictures you opened: a width or a block whose pictures you did not open is not one you looked at.
+   - Each run empties only its own folders before it pictures: `flagged/` every run; `changed/` and `cards/` a plain run; `blocks/` a `--blocks` run; `tiles/` a `--tiles` run. Open a run's pictures before you run the same kind again.
+   - After your last edit, run a plain `gallery qa <slug>`; then, when a line of it says `not pictured` and gives a `gallery qa <slug> --blocks …` command (blocks past a run's twelve, at a list's end; or blocks a tall moved block holds that none of its pictures showed at a width, `N of them not pictured at 360px: …`), run that command too, not instead of it. A `--blocks` run pictures the blocks named alone: its `Not pictured by this run …` line, before the verdict, names the changed blocks and the cards it left, which a plain run pictures.
+   - In the pictures, fix what reads badly though nothing flagged it, such as a single character alone on a line (a heading's or a label's last character wrapped), a line or a mark drawn through text, or one cell or metric left alone on a row of a grid.
+   - To fix what either finds, re-read what the `Re-read` line names, change `doc.html` (never a generated file) and run `gallery qa` again until nothing fails.
+   - Exit 3 is one of two things. `UNVERIFIED <why>: nothing was looked at`: there is no Chrome or Edge, or the one installed did not start (qa tries it twice, with a fresh profile each time). When a browser is installed, run `gallery qa` once more; if it says `UNVERIFIED` again, or there is none, look at the export at those widths yourself, its disclosures and detail cards opened (the page does not scroll sideways, only tables and formula blocks do; no label of a chart or a drawing is clipped, overlaps another or reads under 11px; leave the controls at its top right alone unless the user asks), and say so in the handoff. Or a verdict `nothing failed …; not verified at N places`, with an `UNVERIFIED` line for each place (a wait that ran out, a detail card that did not open, a Sheet panel that stayed hidden, a picture not taken): the rest was looked at; run `gallery qa` once more, then look yourself only at the places those lines name, and say so in the handoff.
+   - `gallery check <slug>` runs the checks alone and changes nothing.
+
+## What the commands print
+
+Paths are absolute, as this system writes them: use them as they are.
+
+| Line | Means |
+| --- | --- |
+| `工作区：<path>` | the workspace the command worked in (`gallery new`, `gallery import`, `gallery list`, `gallery open`, `gallery init`) |
+| `写作偏好：…（<path>）` | where 写作偏好 is (`gallery new`, `gallery import`, `gallery list`): read it before you write (`空`: the user emptied it) |
+| `交给用户（…）：<address>` | the address where the user watches and edits the document: send it to them now, in a message of its own (`gallery new`, `gallery import`, `gallery open`), and again in the handoff |
+| `Agent 自用（…）：<address>` | the document's page alone, editable, with no frame: yours (to try a component in), not for the user |
+| `Wrote: …`, `Undone: …`, `Kept (--keep): …` | `gallery component try`'s: what the gesture wrote to `doc.html`, each part of the instance with the lines it took out and put in, and that one Ctrl+Z gave the file back (`--keep`: the write left); `Picture of the instance after the …` names a picture to open; a `note` line asks what the check's do. In the handoff name each gesture tried and what it wrote |
+| `gallery component try`'s exit code | 0 the gesture wrote and one Ctrl+Z took it back · 1 a problem of the package's (a gesture that wrote nothing, said with what came of it; an undo that left part of the write): fix it, check it, try again; or a `FAIL` saying `doc.html` holds what the gesture wrote, the trial cut off after it: put that back yourself, `doc.html` read again first · 2 a mistake in the command (a selector that finds nothing: the line lists the classes the instance shows) · 3 `UNVERIFIED`, the trial not seen through (no browser or server, a card waiting for the reader, someone else's write meanwhile) and nothing of the gesture left in `doc.html`, its line saying what the file holds: run it once more |
+| `This workspace's Gallery server runs on port …` | the server started or reused: nothing to wait for or keep running |
+| `Preview: not started …` | no server, so no `交给用户` address: run `gallery open <slug> --no-browser` and give the user the address it prints (not in a cloud sandbox they cannot reach) |
+| `Next: …`, `Hand in: …` | the steps after `gallery new` or `gallery import`: follow them |
+| `Cannot write the workspace <path> (…)` | ask the user to allow it, or pass `--workspace <a folder you may write>` |
+| `FAIL <slug>: N problems` | the checks failed, nothing exported (exit 1): fix each |
+| `OK <slug>`, `Checked N documents: …` | `gallery check`'s tally: those passed |
+| `fix …` | act on it (a path of this machine, a heavy picture) |
+| `note …` | advice, never a failure |
+| `note … kept by the script: .x` | your script selects that block by these names, so the user cannot delete or convert it: rename a class or id the script does not select it by |
+| `icon … the page's header none` | write the icon in the header, or take `icon` out of `doc.json` |
+| `Re-read <files> …` | the tools wrote these: re-read exactly them before editing |
+| `preview …`, `annotations …` | said once: which of your plain HTML the browser page made the kit's markup (never the user's edits); 批注 Gallery's server deleted, their words gone from the blocks they are on (`gallery export`, `gallery check` and `gallery qa` say it right after the write) |
+| `交给用户（离线文件）：<path>` | the deliverable (the export's last line; qa's last lines, after its verdict) |
+| `natural <file>: … rewritten in this file as the kit's markup` | the export rewrote those elements of `doc.html`, by line, into the kit's markup (a `<pre>` became `div.doc-code`, its `language-x` moved to `data-language`): nothing to fix, but the file is not what you wrote: re-read it, as the `Re-read` line names it, before you edit it (from `gallery check`: `not rewritten yet`, the export will). The indented lines under it say, by line, what the conversion did with an element (`line 12, code: tabindex kept on its <pre>`): nothing to fix, unless a line says what to write |
+| `Exported <path> …` and other `title`, `icon`, `ids` lines | what the export did (or, from `gallery check`, will do): nothing to do |
+| `chart …` | how a chart drawn from a table reads it (its rows, each column numbers or words): nothing to do |
+| qa `FAIL` · `WARN` · `INFO` | fix it · look at its picture and fix what reads badly, never cutting words or columns · nothing to do |
+| qa `UNVERIFIED <why>: nothing was looked at` · an `UNVERIFIED` line among the findings | nothing looked at: run qa once more, then look at the export yourself and say so · that place alone not looked at (the rest was): run qa once more, then look yourself at that place and say so |
+| `Not pictured by this run …` | a `--blocks` run's: blocks changed and cards it did not picture (with `no earlier look`, every card outside those named); the plain `gallery qa <slug>` it names pictures them |
+| `gallery qa`'s exit code | 0 nothing failed (warnings may remain) · 1 a failure, or the export it ran first failed · 2 an export missing or stale with `--no-export`, or `--blocks` naming an id the document has not (nothing looked at, no picture removed: name ids as qa printed them) · 3 something not verified: nothing at all (`UNVERIFIED <why>`: no Chrome or Edge, or one that did not start), or the places its `UNVERIFIED` lines name |
+| qa's lines per width (`1024px  fail 0 · …`) | what that look found; `1024×768` is the 1024px page in a shorter window |
+
+## Revising a document
+
+When the user names a document by its title or topic, find it with `gallery list <words>` (words of its title or topic; `gallery list` alone lists every document, the one edited last first): it prints each document's slug, title, description, address, last edit and file. An address the user gives (`http://127.0.0.1:<port>/#<title words>-<page id>`, the workbench's address bar or 复制块链接, `/<block id>` after it for a block) names its document by the id at its end, and the words before it may be out of date: `gallery list <address>` prints that document, or says it is in the trash, and every command that takes a slug takes the address, or the link after its `#`, as well. The id comes from the folder's name, so an address from another workspace can name this workspace's folder of that name: before you change anything, compare the title `gallery list <address>` prints, and its `工作区：` line, with what the user means. A path the user gives (the workbench's 复制底稿路径 copies one) is that document's `doc.html`; its folder's name is its slug, the folder holding it the workspace (pass it as `--workspace` when it is not the one the commands find).
+
+Before you change anything, run `gallery open <slug> --no-browser` and give the user the address on its `交给用户` line, even when they say the page is open: it reuses the running server without opening another tab, and it keeps the document as it stands so that the first `gallery qa` pictures what you change. It prints no `写作偏好` line: read `<workspace>/preferences.md` before you change anything.
+
+A long `doc.html` may not fit one read: map it first with a search of its headings and ids (`<h2`, `<h3`, `data-block-id`, with line numbers), then read the part you change by its lines. Right before each change, re-read the part you change and replace only it; never rewrite the whole file from an earlier read or regenerate it with a script. A script may read the file at that moment, replace several exact spans, each found once in it, and write it once (its read is the re-read); it stops without writing when a span is missing or repeated. Write it for Node (`node`), which Gallery runs on and so is always there: `python` may be missing, or a stub that runs nothing and says nothing (Windows' app alias). Keep the start tag of each block you change: its `data-block-id`, `style` and classes may be the user's edits.
+
+Write a block you add or convert as [the example](references/example-report.html) and [writing-html.md](references/writing-html.md) write it: read its part in both first.
+
+- `data-block-id` is a block's identity: never invent one or put one on another element. A moved block, or one wrapped in a new container, keeps its id (cut and paste the element as it is; the container gets none). An added or copied block has none: strip a copy's ids. A split keeps the id on the first part, a merge the first block's; a deleted id is never reused.
+- Words that stay a block's own through a change of type keep its id on the element holding them (a paragraph made an `h3` or `li`: on it); words that become part of another component (a table's numbers moved into a chart's JSON, items a disclosure's title) are a new block, without one. A table given `data-doc-chart` stays its block; its chart card is new. A list made a flowchart, or a flowchart a list, is new as the browser page makes it: no id on it, its nodes or items, or their titles; the blocks its items held keep theirs. Never move an id from an item or a container onto a paragraph in it.
+- When unsure, drop the id: a missing one costs the user at most a choice card, a misplaced one can send their undo to the wrong block. When a check says an id repeats, remove it from the copy.
+- A block made another (a table made Sheet tabs, a list a flowchart) carries every fact of the old one: its numbers, units, scope line and colors, the specific values where the document has them, not a vaguer word. Say in the handoff what could not go.
+- After `gallery export` or the user's first edit in the browser, the file holds the kit's markup and ids: re-read it. The user's edits are in the file itself; no command lists them.
+- A change that takes several edits (blocks wrapped in a disclosure, a section moved, a Sheet area's tabs and panels): make them one right after another. The browser page waits until the file is whole again before it shows it or merges the user's edits into it. A script as above may make a move in one write, cutting and pasting, when every span it cuts and every anchor it pastes at appears once in the file.
+- A revision may need changes the user did not name: a term defined where it now first appears, a reference to what was renamed. You may make them; name each in the handoff.
+- When the change touches data, recheck the summary, charts, units and denominators using it. A summary made simpler still rests each comparison on a number the document shows, and keeps what each number is (a range, a basin, one seed's value, a mean), not only the number. Then export and run `gallery qa`; name the changed blocks in the handoff.
+- The user's 批注 on a document are in `<workspace>/<slug>/annotations.json` (also what the workbench's 复制批注 hands over): `items`, each `{ id, text, anchor: { blocks, quote, … } }`, `text` the user's suggestion (empty: it only marks that place, nothing asked), `quote` the words it is on. When the user asks you to work through them, carry out each `text` where it is anchored; leave one that does not fit its words and ask about it in the handoff; where one conflicts with the request, the request wins: name it. Never edit `annotations.json`. Gallery's server deletes a 批注 whose words are gone, whether the page is open or not: its words must stay in the blocks it is on (`anchor.blocks`), and words moved into another block, a new callout for one, are gone for it (only a 批注 whose blocks are all gone, a block replaced whole, follows its words to where they appear once in the document). `gallery export`, `gallery check` and `gallery qa` list each deleted, once, right after the write that deleted it; run `gallery check <slug>` once more right before the handoff. One you carried out whose words remain stays until the user deletes it. In the handoff, say which you carried out (those still shown, for the user to delete), which you left and which went with their words.
+
+## Output contract
+
+- `<workspace>/<slug>/doc.html` and `doc.json` are the editable sources; what Gallery keeps of its own is under `<workspace>/.gallery/`, never yours to edit; `<workspace>/components/` holds component packages, no document, and is no slug a new document can take; `<workspace>/exports/<slug>.html` is the offline, single-file deliverable. Re-export after the last source edit. In the handoff the clickable HTML is the export or a verified byte-identical copy of it, never a source or a page of the local server.
+- Everything document-specific (data, visuals, styles, scripts) stays in `doc.html` and its `assets/`. Gallery's shared kit (its blocks, styles and `sdk/` types) is not yours to change; the workspace's component packages are. A document uses the kit's blocks and whole blocks. Make a package only when the user clearly wants a block to use again, never one per document: run `gallery component list` first, then read [references/building-components.md](references/building-components.md). When the user wants a document that uses it too, create that document first, even when they say to make the block first: Workflow steps 1–3 (`gallery new`, the address sent), then its skeleton with the heading of the section the instance goes in. Then make the package, and write the instance into its section last. An instance of a package `gallery component list` gives is written as `gallery component show <id>` prints.
+
+## Handoff
+
+In the handoff, give:
+
+- the deliverable: the path on the `交给用户（离线文件）：` line that `gallery export` prints last and `gallery qa` prints after its verdict, copied whole (no `…`, never rebuilt in another folder); and the address on the `交给用户` line of `gallery new` or `gallery open` again (you sent it at the start), where the user edits the document (not in a cloud sandbox they cannot reach). The export holds the document as of your last export: an edit after it, the user's in the browser included, needs another export;
+- what `gallery qa` flagged and what you fixed, and the pictures you opened, by name (never a width or a block whose pictures you did not open); or that it could not run;
+- the sentences that are your own inference and not stated by the materials, with where they are;
+- for a revision, the blocks you changed, the changes the user did not name, what a conversion dropped, and what a change of structure left side by side (two headings of one name, one right after the other, after a move).
+
+Before you hand over, do the review 写作偏好 asks for before handing in (a reading by a subagent, a check of the numbers), when it asks for one.
+
+## References
+
+| Need | Read |
+| --- | --- |
+| The user's rules for writing: what to write, the opening summary, titles, fidelity, evidence and data | 写作偏好, `<workspace>/preferences.md` |
+| How a block is written | [references/example-report.html](references/example-report.html) |
+| The rules behind the blocks: the page, what plain HTML becomes, figures and charts you draw yourself | [references/writing-html.md](references/writing-html.md) |
+| A block to use again, when the user asks for one | [references/building-components.md](references/building-components.md) |
+| Exact API types | `sdk/*.d.ts`, from [`sdk/index.d.ts`](sdk/index.d.ts) |
+| What each command does and prints | `gallery help`, `gallery <command> --help` |

package/skill/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Gallery"
+  short_description: "Turn materials into polished interactive HTML documents"
+  brand_color: "#2678D8"
+  default_prompt: "Use $gallery to turn these materials into a polished interactive HTML document."