@iyulab/u-board-designer 0.0.0-stage → 0.2.0

package/dist/lib/authoring/scene-mapping.js

@@ -0,0 +1,124 @@
+import { Scene } from '@canvas-kit/core';
+import { mayLoadBackground, sizedNodes } from '@iyulab/u-board/toolkit';
+import { decorationObjects } from '@iyulab/u-board/toolkit';
+import { captionObjects, connectorObjects } from '@iyulab/u-board/toolkit';
+/** The stroke a rect decoration is drawn with in the designer when the document does not set its own — distinct
+ * from a node placeholder's blue (`NODE_PLACEHOLDER_STROKE` below) so a structural frame reads apart from a widget
+ * footprint at a glance. */
+const DECORATION_STROKE = '#f59e0b';
+/** A node's placeholder fill/stroke in the designer canvas — the box being positioned, not the
+ * widget itself. The real widget renders in the live preview pane (`resolveDocument` +
+ * `toCanvasKit`), which is the render path the renderer/editor separation already owns; the
+ * designer only needs a draggable, identifiable footprint (docs/principles.md). */
+const NODE_PLACEHOLDER_FILL = 'rgba(59, 130, 246, 0.15)';
+const NODE_PLACEHOLDER_STROKE = '#3b82f6';
+/** A rect decoration's placeholder fill in the designer canvas only — Konva hit-tests a shape by
+ * what it actually draws, so an unfilled rect (the usual authored look for a "frame" that
+ * shouldn't obscure the nodes it groups) is only clickable along its thin stroke line, not its
+ * interior. This translucent fill exists purely to make the whole footprint selectable/draggable
+ * in the designer; it is never written back to the document (`applySceneToDocument` below only
+ * folds back position/size) — the live preview pane and the real renderer still draw the
+ * decoration's own authored `fill` (or none), same as `NODE_PLACEHOLDER_FILL` never leaks into a
+ * node's actual widget appearance. */
+const DECORATION_PLACEHOLDER_FILL = 'rgba(245, 158, 11, 0.08)';
+/**
+ * Projects a ViewDocument into a canvas-kit Scene the designer can render and let the author
+ * drag: the background image (locked, drawn but not editable), the connectors (fixed: selected to edit
+ * them, never dragged — they follow their nodes), and one `rect` per node, id'd by node id, standing in
+ * for its widget's footprint. A scene object's id names its document part, after a `#` for a part's
+ * pieces (`partOf`).
+ */
+export function documentToScene(doc, movable, selectable) {
+    const scene = new Scene();
+    // Only the nodes `movable` names — and the connectors and decorations `selectable` names — when a layout is all that
+    // is edited; else every part of the board's own.
+    const own = new Set((movable
+        ? [...doc.nodes.filter(node => movable(node.id)), ...[...doc.connectors, ...(doc.decorations ?? [])].filter(piece => selectable?.(piece.id))]
+        : [...doc.nodes, ...doc.connectors, ...(doc.decorations ?? [])]).map(part => part.id));
+    // A part not edited here, and every piece of it: drawn, never selected or moved.
+    const add = (object) => scene.add(object.id && !own.has(partOf(object.id)) ? { ...object, locked: true } : object);
+    // A picture outside the origins the host allowed is not requested here either: the board is drawn on an empty background.
+    if (doc.background.image && mayLoadBackground(doc.background.image.src)) {
+        add({
+            type: 'image',
+            x: 0,
+            y: 0,
+            width: doc.background.image.width,
+            height: doc.background.image.height,
+            src: doc.background.image.src,
+            // The picture the board is built on: drawn under the nodes, never grabbed and moved with them.
+            locked: true,
+        });
+    }
+    for (const shape of doc.decorations ?? []) {
+        const [drawn, ...name] = decorationObjects(shape, doc.appearance, doc.accent);
+        if (drawn.type === 'rect') {
+            // Konva's Text hit-tests its full bounding box regardless of fill, so a text decoration is
+            // added as drawn below; a rect decoration needs the designer-only placeholder fill above to
+            // stay clickable across its interior, not just its stroke.
+            add({ ...drawn, fill: DECORATION_PLACEHOLDER_FILL, stroke: drawn.stroke ?? DECORATION_STROKE });
+            // Its name follows the frame — drawn again where the frame lands — and a press on it reaches the frame.
+            for (const object of name)
+                add({ ...object, locked: true });
+        }
+        else {
+            add(drawn);
+        }
+    }
+    // Follows its two nodes: selected to be edited, never dragged — moving a line or its label would move nothing.
+    const nodes = sizedNodes(doc);
+    for (const object of connectorObjects(nodes, doc.connectors, doc.appearance, { fixed: true }, doc.accent))
+        add(object);
+    for (const object of captionObjects(nodes, doc.appearance, true))
+        add(object);
+    for (const node of nodes) {
+        add({
+            type: 'rect',
+            id: node.id,
+            x: node.x,
+            y: node.y,
+            width: node.width,
+            height: node.height,
+            fill: NODE_PLACEHOLDER_FILL,
+            stroke: NODE_PLACEHOLDER_STROKE,
+            strokeWidth: 1,
+        });
+    }
+    return scene;
+}
+/**
+ * Folds a designer Scene's node-rect and decoration-shape positions back into a ViewDocument.
+ * Reads every scene object whose id matches a node or decoration — not just the one the author
+ * just dragged — so it stays correct regardless of how the designer reports the change (single
+ * move, batched drag, resize). A node and a decoration can both be scene `rect`s with the same
+ * shape; they're told apart by id membership in `doc.nodes`/`doc.decorations`, not by scanning
+ * order, so a decoration id never gets folded onto a node or vice versa.
+ */
+export function applySceneToDocument(doc, scene) {
+    const objectsById = new Map(scene.getObjects().filter(obj => !!obj.id).map(obj => [obj.id, obj]));
+    const nodes = doc.nodes.map(node => {
+        const obj = objectsById.get(node.id);
+        if (!obj || obj.type !== 'rect')
+            return node;
+        return { ...node, x: obj.x, y: obj.y, width: obj.width, height: obj.height };
+    });
+    const decorations = doc.decorations?.map((shape) => {
+        const obj = objectsById.get(shape.id);
+        if (!obj)
+            return shape;
+        if (shape.type === 'rect' && obj.type === 'rect') {
+            return { ...shape, x: obj.x, y: obj.y, width: obj.width, height: obj.height };
+        }
+        if (shape.type === 'text' && obj.type === 'text') {
+            return { ...shape, x: obj.x, y: obj.y };
+        }
+        return shape;
+    });
+    return { ...doc, nodes, ...(decorations ? { decorations } : {}) };
+}
+/** The document part a scene object draws: its id, or a part's own id before the `#` of one of its pieces (a
+ * connector's `#chip`, `#arrow0`). */
+export function partOf(objectId) {
+    const at = objectId.indexOf('#');
+    return at === -1 ? objectId : objectId.slice(0, at);
+}

package/dist/lib/authoring/use-edit-keys.d.ts

@@ -0,0 +1,13 @@
+import { type Dispatch, type SetStateAction } from 'react';
+import { type DocumentHistory } from './document-history.js';
+/**
+ * An editor's keys and typing, heard anywhere in its root (its board, its panels): Ctrl+Z (⌘Z) undoes, Ctrl+Shift+Z or
+ * Ctrl+Y redoes — but in a field being typed into, the field's own undo — and focus moving on ends a run of typing.
+ * Returns the ref for the editor's root, and `typing`: the field an input is on its way through now — an edit made then
+ * is one with those typed in the same field before it (`recordEdit`'s `typingIn`), so it is read when the edit is made,
+ * not when its update runs.
+ */
+export declare function useEditKeys<D>(setHistory: Dispatch<SetStateAction<DocumentHistory<D>>>, canUndo: boolean, canRedo: boolean): {
+    rootRef: import("react").RefObject<HTMLDivElement | null>;
+    typing: import("react").RefObject<HTMLElement | null>;
+};

package/dist/lib/authoring/use-edit-keys.js

@@ -0,0 +1,57 @@
+import { useEffect, useEffectEvent, useRef } from 'react';
+import { endTyping, redo, textEntry, undo } from './document-history.js';
+/**
+ * An editor's keys and typing, heard anywhere in its root (its board, its panels): Ctrl+Z (⌘Z) undoes, Ctrl+Shift+Z or
+ * Ctrl+Y redoes — but in a field being typed into, the field's own undo — and focus moving on ends a run of typing.
+ * Returns the ref for the editor's root, and `typing`: the field an input is on its way through now — an edit made then
+ * is one with those typed in the same field before it (`recordEdit`'s `typingIn`), so it is read when the edit is made,
+ * not when its update runs.
+ */
+export function useEditKeys(setHistory, canUndo, canRedo) {
+    const rootRef = useRef(null);
+    const typing = useRef(null);
+    const handleKey = useEffectEvent((e) => {
+        if (!(e.ctrlKey || e.metaKey) || e.altKey || textEntry(e.target))
+            return;
+        const key = e.key.toLowerCase();
+        const back = key === 'z' && !e.shiftKey;
+        const forward = (key === 'z' && e.shiftKey) || (key === 'y' && !e.shiftKey);
+        if (!back && !forward)
+            return;
+        e.preventDefault();
+        if (back && canUndo)
+            setHistory(undo);
+        if (forward && canRedo)
+            setHistory(redo);
+    });
+    useEffect(() => {
+        const root = rootRef.current;
+        if (!root)
+            return;
+        const keyDown = (e) => handleKey(e);
+        const focusMoved = () => setHistory(endTyping);
+        // A field's input is caught on its way down, before the editor's handlers answer it, and let go once it has risen
+        // past them all (to the window).
+        const typed = (e) => {
+            typing.current = textEntry(e.target);
+        };
+        const answered = () => {
+            typing.current = null;
+        };
+        root.addEventListener('keydown', keyDown);
+        root.addEventListener('focusin', focusMoved);
+        for (const type of ['input', 'change']) {
+            root.addEventListener(type, typed, true);
+            window.addEventListener(type, answered);
+        }
+        return () => {
+            root.removeEventListener('keydown', keyDown);
+            root.removeEventListener('focusin', focusMoved);
+            for (const type of ['input', 'change']) {
+                root.removeEventListener(type, typed, true);
+                window.removeEventListener(type, answered);
+            }
+        };
+    }, [setHistory]);
+    return { rootRef, typing };
+}

package/dist/lib/authoring/widget-catalog.d.ts

@@ -0,0 +1,4 @@
+import '@iyulab/u-widgets/tools/locales/ko';
+/** What a widget is called where the editor names it: a prepared widget's name from the widget library, in `locale`,
+ *  or the name of the board's element it places. */
+export declare function widgetTypeName(type: string, locale?: string): string;

package/dist/lib/authoring/widget-catalog.js

@@ -0,0 +1,9 @@
+import { getWidgetLabel } from '@iyulab/u-widgets/tools';
+// The widget library's names in Korean, for `widgetTypeName` — authoring code only, as in widget-fields.ts.
+import '@iyulab/u-widgets/tools/locales/ko';
+import { elementNameOf } from '@iyulab/u-board/toolkit';
+/** What a widget is called where the editor names it: a prepared widget's name from the widget library, in `locale`,
+ *  or the name of the board's element it places. */
+export function widgetTypeName(type, locale) {
+    return elementNameOf(type) ?? getWidgetLabel(type, locale);
+}

package/dist/lib/authoring/widget-fields.d.ts

@@ -0,0 +1,45 @@
+import '@iyulab/u-widgets/tools/locales/ko';
+import type { ElementDefinition, PropsSchema, Widget } from '@iyulab/u-board/picture';
+/** A value of a widget's props the property panel offers its own control for. */
+export interface WidgetField {
+    /** Which group it is shown in: a prepared widget's `props.data` or `props.options`, an element's own props, or a
+     *  component instance's parameter values. */
+    section: 'data' | 'options' | 'element' | 'params';
+    /** Where it lives in the widget's props — also the path a binding that fills it names (`data.value`, `level`). */
+    path: readonly string[];
+    key: string;
+    /** Its name, in the requested language, from the widget library — or an element's `title`. */
+    label: string;
+    kind: 'text' | 'number' | 'boolean' | 'choice';
+    /** The values a `choice` field takes. */
+    choices?: readonly string[];
+    /** Bounds of a `number` field, and whether it takes whole numbers only. */
+    min?: number;
+    max?: number;
+    integer?: boolean;
+    /** What the widget uses when the value is left out, when the widget library says. */
+    defaultValue?: unknown;
+    /** What the widget library says the value is. */
+    description?: string;
+}
+export interface WidgetFields {
+    fields: WidgetField[];
+    /** Options the widget reads that have no control here (lists, objects) — edited as JSON instead. */
+    otherOptions: number;
+}
+/** The fields of an object schema — an element's props, a component's parameters: one per property it lists, in the
+ *  schema's order; a property no control edits (a list, an object) is counted in `otherOptions`. */
+export declare function schemaFields(schema: PropsSchema | undefined, section: WidgetField['section']): WidgetFields;
+/**
+ * The fields of `widget` the panel can edit with a control. For a prepared widget, as the widget library describes
+ * them (`@iyulab/u-widgets/tools`): its known data fields — when `props.data` is a single object; data given as an
+ * array of rows is edited as JSON — and the options it reads whose value is a text, a number, a yes/no or a choice.
+ * For an element (`element:<name>`), the props its definition in `elements` lists. Anything else stays in the JSON
+ * editor. Names are in `locale` (the labels' language).
+ */
+export declare function widgetFields(widget: Widget, locale?: string, elements?: Readonly<Record<string, ElementDefinition>>): WidgetFields;
+/** The value of `field` in `widget`'s props, or `undefined` when it is not set. */
+export declare function readField(widget: Widget, field: Pick<WidgetField, 'path'>): unknown;
+/** `widget` with one field set — or removed, when `value` is `undefined`. Everything else in its props (mapping,
+ * other options, keys this panel does not know) is kept as it was; an `options` object left empty goes too. */
+export declare function withField(widget: Widget, field: Pick<WidgetField, 'path'>, value: unknown): Widget;

package/dist/lib/authoring/widget-fields.js

@@ -0,0 +1,129 @@
+import { getWidgetDataFields, getWidgetOptions } from '@iyulab/u-widgets/tools';
+// The widget library's names in Korean — the language U-Board ships labels for besides English
+// (`KO_LABELS`). Registered here, with the authoring code, so a viewer never loads them.
+import '@iyulab/u-widgets/tools/locales/ko';
+import { elementNameOf } from '@iyulab/u-board/toolkit';
+/** The control for a value of `type` (in the widget library's notation), or none for a list or an object. */
+function kindOf(type, choices) {
+    if (choices)
+        return { kind: 'choice', choices };
+    if (type === 'string')
+        return { kind: 'text' };
+    if (type === 'number')
+        return { kind: 'number' };
+    if (type === 'boolean')
+        return { kind: 'boolean' };
+    return undefined;
+}
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** The control for a prop an element's schema describes, or none for one edited as JSON (a list, an object, a
+ *  value of several types, a choice that is not all text). */
+function schemaKind(schema) {
+    if (schema.enum !== undefined) {
+        return schema.enum.every(value => typeof value === 'string') ? { kind: 'choice', choices: schema.enum } : undefined;
+    }
+    switch (schema.type) {
+        case 'string':
+            return { kind: 'text' };
+        case 'number':
+        case 'integer':
+            return {
+                kind: 'number',
+                ...(schema.minimum !== undefined && { min: schema.minimum }),
+                ...(schema.maximum !== undefined && { max: schema.maximum }),
+                ...(schema.type === 'integer' && { integer: true }),
+            };
+        case 'boolean':
+            return { kind: 'boolean' };
+        default:
+            return undefined;
+    }
+}
+/** The fields of an object schema — an element's props, a component's parameters: one per property it lists, in the
+ *  schema's order; a property no control edits (a list, an object) is counted in `otherOptions`. */
+export function schemaFields(schema, section) {
+    const fields = [];
+    let otherOptions = 0;
+    for (const [key, property] of Object.entries(schema?.properties ?? {})) {
+        const kind = schemaKind(property);
+        if (!kind) {
+            otherOptions++;
+            continue;
+        }
+        fields.push({
+            section,
+            path: [key],
+            key,
+            label: property.title ?? key,
+            ...kind,
+            ...(property.default !== undefined && { defaultValue: property.default }),
+            ...(property.description !== undefined && { description: property.description }),
+        });
+    }
+    return { fields, otherOptions };
+}
+/** The fields of a placed element: one per prop its definition's schema lists, in the schema's order. */
+function elementFields(definition) {
+    return schemaFields(definition?.props, 'element');
+}
+/**
+ * The fields of `widget` the panel can edit with a control. For a prepared widget, as the widget library describes
+ * them (`@iyulab/u-widgets/tools`): its known data fields — when `props.data` is a single object; data given as an
+ * array of rows is edited as JSON — and the options it reads whose value is a text, a number, a yes/no or a choice.
+ * For an element (`element:<name>`), the props its definition in `elements` lists. Anything else stays in the JSON
+ * editor. Names are in `locale` (the labels' language).
+ */
+export function widgetFields(widget, locale, elements) {
+    const element = elementNameOf(widget.type);
+    if (element !== undefined)
+        return elementFields(elements && Object.hasOwn(elements, element) ? elements[element] : undefined);
+    const props = isRecord(widget.props) ? widget.props : {};
+    const fields = [];
+    if (props.data === undefined || isRecord(props.data)) {
+        for (const field of getWidgetDataFields(widget.type, locale)) {
+            const kind = kindOf(field.type, field.enum);
+            if (kind)
+                fields.push({ section: 'data', path: ['data', field.key], key: field.key, label: field.label, ...kind, description: field.desc });
+        }
+    }
+    let otherOptions = 0;
+    for (const option of getWidgetOptions(widget.type, locale)) {
+        const kind = kindOf(option.type, option.enum);
+        if (!kind) {
+            otherOptions++;
+            continue;
+        }
+        fields.push({
+            section: 'options',
+            path: ['options', option.key],
+            key: option.key,
+            label: option.label,
+            ...kind,
+            ...(option.default !== undefined && { defaultValue: option.default }),
+            description: option.desc,
+        });
+    }
+    return { fields, otherOptions };
+}
+/** The value of `field` in `widget`'s props, or `undefined` when it is not set. */
+export function readField(widget, field) {
+    let value = widget.props;
+    for (const segment of field.path)
+        value = isRecord(value) ? value[segment] : undefined;
+    return value;
+}
+/** `widget` with one field set — or removed, when `value` is `undefined`. Everything else in its props (mapping,
+ * other options, keys this panel does not know) is kept as it was; an `options` object left empty goes too. */
+export function withField(widget, field, value) {
+    const set = (container, path) => {
+        const next = isRecord(container) ? { ...container } : {};
+        const [head, ...rest] = path;
+        const child = rest.length === 0 ? value : set(next[head], rest);
+        if (child === undefined || (head === 'options' && isRecord(child) && Object.keys(child).length === 0))
+            delete next[head];
+        else
+            next[head] = child;
+        return next;
+    };
+    return { ...widget, props: set(widget.props, field.path) };
+}

package/dist/lib/board/check.d.ts

@@ -0,0 +1,27 @@
+import type { ViewKind } from '@iyulab/u-board/picture';
+import type { Board } from '@iyulab/u-board/domain';
+/** A problem or a piece of advice, at a JSON Pointer into the board. */
+export interface BoardFinding {
+    path: string;
+    message: string;
+}
+/** What a board is refused for (`issues`), and — when there is nothing to refuse — what could be written better
+ *  (`advice`). */
+export interface BoardCheck {
+    issues: BoardFinding[];
+    advice: BoardFinding[];
+}
+/** A board with no parts yet, laying out `kind` — what a new board starts as. A canvas is 1280 × 720 until it is resized. */
+export declare function emptyBoard(kind: ViewKind): Board;
+export declare function checkBoard(board: unknown): BoardCheck;
+/** A data source of the workspace a board is saved in, as a board names it: by its id. */
+export interface KnownSource {
+    id: string;
+    name: string;
+}
+/**
+ * The data reads whose `from` names no data source of the workspace — read by a connector's request (`path`), so it is
+ * one of the workspace's sources or nothing reads it — each at its `from`, saying which id to write when it names a
+ * source by its name. Advice, not a refusal: a source may be removed after a board reads it, and the board still saves.
+ */
+export declare function sourceAdvice(board: Board, sources: readonly KnownSource[]): BoardFinding[];

package/dist/lib/board/check.js

@@ -0,0 +1,48 @@
+// The check a board meets before it is stored: its language (`validateBoard`), and
+// then that it draws — a part the renderer cannot draw yet is refused when it is written, not on the page that shows it.
+// The server's save and an assistant's tools check with this, so both refuse the same boards in the same words.
+import { PictureError, toViewDocument } from '@iyulab/u-board/domain';
+import { validateBoard } from '@iyulab/u-board/domain';
+/** The items a part made per item stands for when a board is checked: none — a board draws before its data has any
+ *  items, and the items it has later do not change what it is. */
+const NO_ITEMS = { keysOf: () => [], rowsOf: () => [] };
+/** A board with no parts yet, laying out `kind` — what a new board starts as. A canvas is 1280 × 720 until it is resized. */
+export function emptyBoard(kind) {
+    return {
+        parts: {},
+        layout: kind === 'grid' ? { kind: 'grid', items: [] } : { kind: 'canvas', size: [1280, 720], place: {} },
+    };
+}
+export function checkBoard(board) {
+    const found = validateBoard(board);
+    const issues = found.filter(f => !f.hint).map(({ at, message }) => ({ path: at, message }));
+    if (issues.length === 0) {
+        try {
+            toViewDocument(board, NO_ITEMS);
+        }
+        catch (error) {
+            if (!(error instanceof PictureError))
+                throw error;
+            issues.push({ path: error.at, message: error.message.slice(error.at.length + 2) });
+        }
+    }
+    return { issues, advice: issues.length > 0 ? [] : found.filter(f => f.hint).map(({ at, message }) => ({ path: at, message })) };
+}
+/**
+ * The data reads whose `from` names no data source of the workspace — read by a connector's request (`path`), so it is
+ * one of the workspace's sources or nothing reads it — each at its `from`, saying which id to write when it names a
+ * source by its name. Advice, not a refusal: a source may be removed after a board reads it, and the board still saves.
+ */
+export function sourceAdvice(board, sources) {
+    const ids = new Set(sources.map(s => s.id));
+    return Object.entries(board.data ?? {}).flatMap(([name, query]) => {
+        if (query.path === undefined || typeof query.from !== 'string' || ids.has(query.from))
+            return [];
+        const said = query.from.trim().toLowerCase();
+        const named = sources.filter(s => s.name.trim().toLowerCase() === said);
+        const message = named.length === 1
+            ? `"${query.from}" is the name of a data source — "from" takes its id: "${named[0].id}". Nothing is read until it does`
+            : `"${query.from}" is no data source of this workspace — "from" takes a source's id (list_sources). Nothing is read until it does`;
+        return [{ path: `/data/${name.replace(/~/g, '~0').replace(/\//g, '~1')}/from`, message }];
+    });
+}

package/dist/lib/board/rulebook.d.ts

@@ -0,0 +1,7 @@
+import { type Board } from '@iyulab/u-board/domain';
+/** A worked board: one read of a list, statuses, a status card per item, a chart and a link — valid as written. */
+export declare const RULEBOOK_EXAMPLE: Board;
+/** The rulebook, as Markdown. */
+export declare function boardRulebook(): string;
+/** The options every `chart.*` kind takes — the data columns and the like — said once under the table, not on each chart's row. */
+export declare function sharedChartOptions(): string[];

package/dist/lib/board/rulebook.js

@@ -0,0 +1,148 @@
+// The rulebook an assistant reads to write a board. What the code knows — the kinds a
+// part may be and their options, the tones, the emphases, the frames, the keys of a data read and of a link — is
+// generated from the same lists the schema and the check read, so the rulebook never lists a kind the check refuses or
+// leaves one out. Only what the code cannot say — why a board is written this way — is prose.
+import { PART_KINDS } from '@iyulab/u-board/domain';
+import { boardSchema } from '@iyulab/u-board/domain';
+import { EMPHASES, FRAMES, TONES } from '@iyulab/u-board/domain';
+/** A worked board: one read of a list, statuses, a status card per item, a chart and a link — valid as written. */
+export const RULEBOOK_EXAMPLE = {
+    statuses: { running: { tone: 'ok', label: '가동' }, down: { tone: 'alarm', label: '정지', emphasis: 'blink' } },
+    data: {
+        pumps: {
+            from: 'plant', path: '/plant/pumps', list: '/value', key: 'id', time: 'updatedAt', fresh: 60,
+            fields: { state: { state: { run: 'running', trip: 'down', '*': 'off' } }, flow: { label: '유량', unit: 'm³/h', digits: 1 } },
+        },
+        hourly: { from: 'plant', path: '/plant/flow/hourly', list: '/value' },
+    },
+    parts: {
+        P1: { as: 'status-card', of: 'pumps[P1]', title: '펌프 1', show: ['state', 'flow'] },
+        P2: { as: 'status-card', of: 'pumps[P2]', title: '펌프 2', show: ['state', 'flow'] },
+        flow: { as: 'chart.line', of: 'hourly', title: '시간대별 유량', x: 'hour', y: 'flow' },
+    },
+    layout: {
+        kind: 'canvas', size: [720, 360],
+        place: { P1: [40, 40, 200, 120], P2: [440, 40, 200, 120], flow: [40, 200, 640, 140] },
+        shapes: { title: { text: '펌프장', at: [40, 24] } },
+        links: { line: { from: 'P1', to: 'P2', of: 'pumps[P1]', show: 'state', label: '{{flow}}', arrow: 'end' } },
+    },
+};
+/** The rulebook, as Markdown. */
+export function boardRulebook() {
+    const schema = boardSchema();
+    const defs = schema.$defs ?? {};
+    const keys = (def, skip = []) => Object.entries(defs[def]?.properties ?? {})
+        .filter(([key]) => !skip.includes(key))
+        .map(([key, p]) => `- \`${key}\`${p.description ? ` — ${p.description}` : ''}`)
+        .join('\n');
+    const code = (words) => words.map(w => `\`${w}\``).join(' · ');
+    return [
+        `# Writing a board
+
+A board is one JSON object. Say once where values come from and what they mean (\`data\`), what is shown (\`parts\`) and
+where (\`layout\`); statuses and the look are said once for the board. Everything is addressed by id; there is one way
+to write each thing.
+
+${['board', 'statuses', 'symbols', 'elements', 'data', 'presets', 'parts', 'layout', 'triggers'].filter(k => k in (schema.properties ?? {})).map(k => `- \`${k}\`${schema.properties[k].description ? ` — ${schema.properties[k].description}` : ''}`).join('\n')}`,
+        `## data — read once, give meaning once
+
+A data read asks an HTTP connector a \`path\` — the usual read. Only an adapter the host names itself is given its own
+\`ref\` instead (one item, its \`fields\` only, never with \`path\`).
+Parts name a read (\`"pumps"\`, the whole list) or one item of it (\`"pumps[P1]"\`, by its \`key\`). Data stays raw —
+names, units, places and statuses live in \`fields\`, never in the data. A field's \`at\` points into one item, so with a \`list\` what sits beside it (a count, a total) is out of reach: read that
+with a read of its own and no \`list\` — \`{ from: 'plant', path: '/plant/pumps?limit=1', fields: { total: { at: '/total' } } }\`. With a \`list\`, \`time\` is a field of each item (an item lacking it has no value); the answer's own is \`answerTime\`.
+
+${keys('query')}
+
+A field is \`{ at?, label?, unit?, digits?, format?, names?, state? }\`; it reads \`/<its name>\` of the item unless \`at\`
+says where. \`state\` says how the value is doing, as a status: \`"raw"\` (the value is a status name), a map
+(\`{ "trip": "down", "*": "off" }\`, \`*\` for the rest) or bands (\`["ok", 1, "warn", 5, "alarm"]\` — the status below the
+first number, then from each number up); a time's \`state\` can follow the clock: \`{ "relative": ["past", -2700, "now", 1, "next", 2700, "later"] }\` — bands over the seconds from now to it (negative: gone by). \`names\` takes the same two forms for what a value is shown as (a word, a count of marks). A field can also be computed from the items of the list: \`derive: { op: count | sum | min | max | avg, field?, where? }\` — a part that reads the list (no item) shows it, a \`state\` on it can raise a status. A field that holds a list of objects says what its items' fields mean with \`items\`.`,
+        `## statuses — how each status looks
+
+Tones (always there): ${code(TONES)}. A board names its own statuses, each with a \`tone\`, a \`label\`, and optionally a
+\`glyph\` and an \`emphasis\` (${code(EMPHASES)}). Anything showing a field with a \`state\` takes its status — colour,
+label, glyph. Never write colours for statuses.`,
+        `## parts — what, of what, which fields
+
+\`{ "as": <kind>, "of": "<data>" | "<data>[<key>]", "show": "<field>" | ["<field>", …], "title"?, …options }\`. \`{{field}}\`
+in a title or a label reads a field of \`of\` (a status card's \`subtitle\` · \`note\` too; header \`kicker\` · \`subtitle\` are fixed text, \`clock\` is \`true\`); \`{{key}}\` is the item's key. \`presets\` hold shared settings a part takes
+with \`use\`; \`each: "<data>"\` makes one part per item (ids \`<part>/<key>\`) — it takes no \`of\`, and is placed once. A \`group\` is several parts on a small
+canvas of their own — its parts and links read the group's \`of\` unless they name their own.
+
+The board's own options take fields of what the part reads: a \`status-card\`'s \`meter\` is \`"<field>"\` or
+\`{ "field", "min"?, "max"? (a number, or a field of the item), "form"?: "bar" | "ring" }\`, its \`state\` (and a \`stat-list\`'s) the field whose status colours
+it, a \`stat\`'s \`trend\` a field holding its recent values, a \`list\`'s \`primary\` · \`secondary\` · \`trailing\` ·
+\`badge\` · \`time\` fields of each row. A part that reads one item takes \`highlight: "<boolean field>"\`: a ring while it is true, apart from the status. Any other option is the widget's own — only those listed.
+
+| kind | shows | reads data | options |
+|---|---|---|---|
+${PART_KINDS.map(kindRow).join('\n')}
+
+Every \`chart.*\` also takes ${code(sharedChartOptions())}.`,
+        `## layout — where, per view kind
+
+- canvas: \`{ "kind": "canvas", "size": [w, h], "background"?, "place": { "<part>": [x, y, w?, h?] }, "shapes"?, "links"? }\` —
+  an \`each\` part is placed item by item inside its own entry (\`{ "P1": [x, y, w, h], … }\`), or — when the items change and cannot be
+  named — by their own fields: \`"quake": { "at": ["lon", "lat"], "frame": [-180, 90, 180, -90], "size": [14, 14] }\` puts each item
+  at the point its two fields say; \`frame\` is the values at the canvas's left, top, right and bottom edges (the canvas's own
+  coordinates when left out), \`size\` the box centred on the point (give one for a marker: a dot alone is [14, 14]; one with a name or note draws
+  it right of the dot — about [150, 40] — and it is the box, not the dot, that is centred). An item with no number in a field, or
+  outside the frame, is not drawn — \`look\` counts them. The data needs a \`key\`; the projection is linear (right for a plan or a flat map). A part is placed one way, not both. Or by a rule: \`"tile": { "flow": { "cell": [w, h], "columns": n, "gap"?, "at"? }, "by"?: "<field>", "boxes"?: { "columns": n, "label"?: "{{key}}" } }\` — items flow in columns, or with \`by\` are grouped into labelled boxes (\`flow.pad\` [sides, top] kept clear inside). A shape is a \`box\` (with \`label\`), a \`text\` at a point,
+  a \`line\` through points or a \`path\` (absolute M · L · C · Q · Z).
+- grid: \`{ "kind": "grid", "items": ["<part>", ["<part>", span], { "grid": [ … ], "span": n }, { "canvas": { … }, "span": n }] }\` —
+  12 columns; an \`each\` part's items are cells (\`["pumps", 2]\`: six to a row); a grid in an item stacks what it holds.
+
+A link joins two parts:
+
+${keys('groupLink')}`,
+        `## elements and the look
+
+Use a built-in whenever one shows the thing — a title, a status and a few values are a \`status-card\`, \`stat\` or
+\`stat-list\`. Write an element only for a drawing no built-in makes:
+\`"elements": { "tank": { "template": "<svg …>{{level}}</svg>", "style"?: "…", "props": { "level": "number", "tone": "string" } } }\`
+— every \`{{hole}}\` is a declared prop (\`number\` · \`string\` · \`boolean\` · \`list\` · \`object\`). A part places it with
+\`"as": "element", "element": "tank"\`, fixed \`props\` and \`bind\` (\`{ "level": "<field>", "tone": "<field>.tone" }\`). What markup cannot draw runs as a
+\`"script"\` in place of the template — in a sandboxed frame with no network, its props through \`ub.onProps\`, \`"resources"\` the
+https:// origins it loads from. The look is \`board.skin\`, once for the board; parts never set fonts or colours:
+\`{ "palette"?: { "paper", "ink", "muted", "rule" }, "font"? · "display"? · "mono"? (font stacks), "frame"?, "radius"? (px), "shadow"?: "none" | "soft" | "hard" }\`
+— a frame is ${code(FRAMES)}; paper is the ground the widgets sit on, ink their text, muted the quieter text, rule their lines; an element's CSS reads them as
+\`var(--u-widget-bg)\` · \`var(--u-widget-text)\` · \`var(--u-widget-text-secondary)\` · \`var(--u-widget-border)\`; a background picture follows the skin when it writes a colour as \`var(--u-widget-bg, #f6f4ef)\` (its own colour is the fallback).`,
+        `## triggers — what the board does
+
+A trigger is \`{ "on", "when"?, "do": [ … ] }\`. \`on\` a part clicked (\`{ "event": "click", "part" }\`), an event its element
+raises (\`"element"\` with \`name\`), a part entering or leaving a status (\`"enter"\` · \`"leave"\` with \`status\`, and the
+\`field\` whose state it is unless the part has its own — a status card's, a \`state\` option's) or the board opened
+(\`"open"\`); \`when\` keeps it to a part in one of the statuses; \`do\` opens a link (\`open-link\`, \`url\` with \`{{part}}\` ·
+\`{{status}}\` · \`{{board}}\` filled in), brings a part into view (\`focus\`), hands the host an event (\`emit\`) or asks for
+another board (\`go-to-board\`). A part made per item is named per item (\`"pumps/P1"\`) — or, in \`on\`, by its own id for every
+item at once (\`{ "event": "click", "part": "pumps" }\`): the event is then about that item, and \`open-link\`'s \`url\` may hold
+\`{{key}}\` (the item's key) and \`{{field}}\` (a field the data declares), each URL-encoded: \`"/orders/{{key}}?line={{line}}"\`.
+The address (scheme, host, port) is written out; the holes go in the path, query or fragment. An item with no value for a field
+gets no link. Triggers only show, move and tell — they write to nothing the board reads.`,
+        `## Rules
+
+- Ids are the keys of each map and unique within it. Never address by index.
+- Every part is placed by the layout; a part placed nowhere is an error.
+- Coordinates appear only in a canvas layout.
+
+## Example
+
+\`\`\`json
+${JSON.stringify(RULEBOOK_EXAMPLE, null, 1)}
+\`\`\``,
+    ].join('\n\n');
+}
+const optionsOf = (k) => [...k.own, ...k.options];
+/** The options every `chart.*` kind takes — the data columns and the like — said once under the table, not on each chart's row. */
+export function sharedChartOptions() {
+    const charts = PART_KINDS.filter(k => k.kind.startsWith('chart.'));
+    return charts.length === 0 ? [] : optionsOf(charts[0]).filter(option => charts.every(k => optionsOf(k).includes(option)));
+}
+/** A kind's row: its name, what it shows, whether it reads data, and its options — the board's own, then the widget's. */
+function kindRow(k) {
+    const reads = { needs: 'yes', may: 'may', no: 'no' }[k.of];
+    const shared = k.kind.startsWith('chart.') ? sharedChartOptions() : [];
+    const options = optionsOf(k).filter(option => !shared.includes(option));
+    return `| \`${k.kind}\` | ${k.shows.replace(/\|/g, '/')} | ${reads} | ${options.length > 0 ? options.map(o => `\`${o}\``).join(' ') : '—'} |`;
+}

package/dist/lib/check-entry.d.ts

@@ -0,0 +1,3 @@
+export { checkBoard, emptyBoard, sourceAdvice } from './board/check.js';
+export type { BoardCheck, BoardFinding, KnownSource } from './board/check.js';
+export { boardRulebook, RULEBOOK_EXAMPLE } from './board/rulebook.js';

package/dist/lib/check-entry.js

@@ -0,0 +1,4 @@
+// What helps a board get written well — the check an author or an assistant reads, and the rulebook an assistant
+// writes by. Reaches no UI package at runtime, so a server or an MCP process loads it.
+export { checkBoard, emptyBoard, sourceAdvice } from './board/check.js';
+export { boardRulebook, RULEBOOK_EXAMPLE } from './board/rulebook.js';