@scrawl-board/board 0.1.0-beta.5 → 0.1.0-beta.7

package/README.md

@@ -27,8 +27,10 @@ undo and redo, zoom and fit, search, JSON import, and PNG, SVG, or JSON export.
 Every control calls a public grouped controller capability. The default keyboard
 surface is scoped to the focused Board: `P` selects marker, `H` selects
 highlighter, `V` selects selection, `E` selects eraser, `N` selects note, `T`
-selects text, `F` fits content, `Mod+Z` undoes, `Mod+Shift+Z` redoes, and `Mod+F`
-opens Board search. Dialogs trap focus, close with Escape, and restore focus to
+selects text, `F` fits content, `Mod+Z` undoes, `Mod+Shift+Z` redoes, `Mod+F`
+opens Board search, and the arrow keys nudge the current selection by a small
+step (`Shift` for a bigger one) across any mix of selected object types, as one
+undo step. Dialogs trap focus, close with Escape, and restore focus to
 their opener. Hosts that replace the default UI can remove it independently while
 retaining `ScrawlProvider` and `ScrawlCanvas`, or disable individual `tools`,
 `history`, `view`, `style`, `search`, `import`, and `export` regions with the

package/dist/browser.d.ts

@@ -355,6 +355,133 @@ interface KitchenTimer extends Lockable {
     runningSince?: number;
 }
 
+interface RectangleObject extends Lockable {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    /** Corner radius in board units; clamped to at most half the shorter side at render time. */
+    cornerRadius?: number;
+    /** `[0, 1]`; undefined means fully opaque (Phase 4). */
+    opacity?: number;
+    /**
+     * Radians, about the shape's own center `(x + width/2, y - height/2)`.
+     * Undefined means 0 (Phase 3). `x`/`y`/`width`/`height` stay in the
+     * shape's own unrotated local frame — rotation is a separate, applied-last
+     * transform, not baked into them, matching how Stroke/CustomBoardObject
+     * keep geometry and placement independent via their own `matrix`.
+     */
+    rotation?: number;
+}
+interface EllipseObject extends Lockable {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    /** `[0, 1]`; undefined means fully opaque (Phase 4). */
+    opacity?: number;
+    /** Radians, about the shape's own center — see RectangleObject's `rotation` doc. */
+    rotation?: number;
+}
+/** `"none"` is a plain line with no arrowhead; today's only real head shape is `"triangle"`. New head shapes extend this union without touching `ArrowObject`'s own fields. */
+type ArrowHeadStyle = "triangle" | "none";
+interface LineObject extends Lockable {
+    id: string;
+    start: BoardPoint;
+    end: BoardPoint;
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+}
+interface ArrowObject extends Lockable {
+    id: string;
+    start: BoardPoint;
+    end: BoardPoint;
+    head?: ArrowHeadStyle;
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+}
+/**
+ * Triangle(3)/Diamond(4)/Pentagon(5)/Hexagon(6)/Octagon(8) as one shared
+ * type instead of five near-duplicate interfaces — a regular N-gon
+ * inscribed in the same `x`/`y`/`width`/`height`/`rotation` bounding box
+ * Rectangle already uses, parameterized by `sides`. Diamond is exactly a
+ * 4-sided regular polygon with vertex 0 pointing right (not up, like
+ * Triangle/Pentagon/Hexagon) — see `polygonGeometry.ts`'s
+ * `polygonStartAngle`, which encodes each side count's own vertex
+ * orientation so the outline always matches the legacy drag-preview shape.
+ */
+interface PolygonObject extends Lockable {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    sides: 3 | 4 | 5 | 6 | 8;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+    /** Radians, about the shape's own center — see RectangleObject's `rotation` doc. */
+    rotation?: number;
+}
+/** Same bounding-box/rotation convention as Rectangle; a 5-pointed star with a tuned inner-radius ratio, matching the legacy tool's own default (see `polygonGeometry.ts`'s `starPoints`). */
+interface StarObject extends Lockable {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Vertex count; today's only shipped preset is 5, matching the legacy tool. */
+    points: number;
+    /** `(0, 1)` — inner vertex radius as a fraction of the outer radius. */
+    innerRadiusRatio: number;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+    rotation?: number;
+}
+/** Same bounding-box/rotation convention as Rectangle; the standard parametric heart curve (see `polygonGeometry.ts`'s `heartPoints`), no extra parameters beyond the shared shape fields. */
+interface HeartObject extends Lockable {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+    rotation?: number;
+}
+/**
+ * A logical grouping of other board objects (Phase 3 — Selection,
+ * Transformation & Grouping). Deliberately has no `x`/`y`/`transform` of its
+ * own — a group's bounds are always derived on demand from its (recursively
+ * resolved) children, and "moving/rotating/scaling the group" is exactly a
+ * multi-object transform applied to those children, nothing more. A group
+ * has no renderer/mesh of its own; its only visual presence is the
+ * selection gizmo's bounding box while it's the current selection.
+ *
+ * `children` may itself contain other group ids (nested groups) — expanding
+ * a group into its leaf members is always done by the caller (recursively,
+ * with cycle protection), never assumed here.
+ */
+interface GroupObject extends Lockable {
+    id: string;
+    children: string[];
+}
+
 interface BoardPoint {
     x: number;
     y: number;
@@ -417,6 +544,31 @@ interface SerializedDocument {
     timers?: KitchenTimer[];
     /** Absent in documents saved before Custom board objects existed (ticket #22). */
     customObjects?: CustomBoardObject[];
+    /** Absent in documents saved before semantic Rectangle objects existed (Phase 2). */
+    rectangles?: RectangleObject[];
+    /** Absent in documents saved before semantic Ellipse objects existed (Phase 2). */
+    ellipses?: EllipseObject[];
+    /** Absent in documents saved before Groups existed (Phase 3). */
+    groups?: GroupObject[];
+    /** Absent in documents saved before semantic Line objects existed (Phase 4). */
+    lines?: LineObject[];
+    /** Absent in documents saved before semantic Arrow objects existed (Phase 4). */
+    arrows?: ArrowObject[];
+    /** Absent in documents saved before semantic Polygon objects existed (Phase 4). */
+    polygons?: PolygonObject[];
+    /** Absent in documents saved before semantic Star objects existed (Phase 4). */
+    stars?: StarObject[];
+    /** Absent in documents saved before semantic Heart objects existed (Phase 4). */
+    hearts?: HeartObject[];
+    /**
+     * Every content-object id (every type above except comments, which are
+     * host-synced and never enter this schema) in paint order, back to front.
+     * Absent in documents saved before per-object z-order existed (Phase 3) —
+     * migration synthesizes a default order preserving the old fixed-Z-band
+     * visual stacking exactly, so an existing document never visibly changes
+     * on load; only an explicit reorder action touches this from then on.
+     */
+    objectOrder?: string[];
 }
 /**
  * One collaborator's vote on a note. One per person; toggling removes it.
@@ -616,7 +768,7 @@ interface BoardSnapshot {
  * here, matching the engine's own internal selection-badge behavior.
  */
 interface FocusedItem {
-    readonly type: "stroke" | "note" | "text" | "table" | "image" | "timer" | "custom";
+    readonly type: "stroke" | "note" | "text" | "table" | "image" | "timer" | "rectangle" | "ellipse" | "group" | "line" | "arrow" | "polygon" | "star" | "heart" | "custom";
     readonly id: string;
     readonly locked: boolean;
     readonly lockedBy?: string;
@@ -798,6 +950,22 @@ type BoardObject = ({
 } & ImageBlock) | ({
     type: "timer";
 } & KitchenTimer) | ({
+    type: "rectangle";
+} & RectangleObject) | ({
+    type: "ellipse";
+} & EllipseObject) | ({
+    type: "group";
+} & GroupObject) | ({
+    type: "line";
+} & LineObject) | ({
+    type: "arrow";
+} & ArrowObject) | ({
+    type: "polygon";
+} & PolygonObject) | ({
+    type: "star";
+} & StarObject) | ({
+    type: "heart";
+} & HeartObject) | ({
     type: "custom";
     customType: ObjectType;
 } & Omit<CustomBoardObject, "type">);
@@ -826,6 +994,30 @@ type BoardObjectInput = {
     type: "timer";
     id?: string;
 } & Omit<KitchenTimer, "id">) | ({
+    type: "rectangle";
+    id?: string;
+} & Omit<RectangleObject, "id">) | ({
+    type: "ellipse";
+    id?: string;
+} & Omit<EllipseObject, "id">) | ({
+    type: "group";
+    id?: string;
+} & Omit<GroupObject, "id">) | ({
+    type: "line";
+    id?: string;
+} & Omit<LineObject, "id">) | ({
+    type: "arrow";
+    id?: string;
+} & Omit<ArrowObject, "id">) | ({
+    type: "polygon";
+    id?: string;
+} & Omit<PolygonObject, "id">) | ({
+    type: "star";
+    id?: string;
+} & Omit<StarObject, "id">) | ({
+    type: "heart";
+    id?: string;
+} & Omit<HeartObject, "id">) | ({
     type: "custom";
     id?: string;
     customType: ObjectType;
@@ -887,7 +1079,16 @@ interface ControllerOp {
     id: string;
     schemaVersion: 1;
     kind: "upsert" | "restore" | "remove";
-    objectType: "stroke" | "note" | "text" | "table" | "image" | "timer" | "custom";
+    objectType: "stroke" | "note" | "text" | "table" | "image" | "timer" | "rectangle" | "ellipse" | "group" | "line" | "arrow" | "polygon" | "star" | "heart" | "custom"
+    /**
+     * A whole-document paint-order sync (Phase 3), not a per-object type —
+     * `objectId` is always the fixed sentinel `"order"` and `payload` is
+     * `{ order: string[] }`. The only `objectType` with no matching
+     * `BoardObject`/document collection; kept in this same union (rather
+     * than a separate wire message) so it flows through the existing
+     * `PersistenceAdapter`/`CollaborationAdapter` opaquely, unchanged.
+     */
+     | "order";
     objectId: string;
     payload?: unknown;
 }
@@ -1000,6 +1201,56 @@ interface BoardController {
          * Unknown ids are silently skipped, matching `remove`'s convention.
          */
         duplicate(ids: readonly string[]): readonly string[];
+        /**
+         * Creates a new Group referencing `ids` as its children and returns its
+         * id, as one undoable step. Unknown ids are silently skipped, matching
+         * `duplicate`/`remove`'s convention. A child id that's itself a group
+         * makes a nested group — expanding nested groups into their leaf
+         * members is always the caller's job, never assumed here (matches the
+         * document-model `GroupObject` itself).
+         */
+        group(ids: readonly string[]): string;
+        /**
+         * Dissolves one group, returning its immediate children's ids (a nested
+         * subgroup among them stays intact, itself still a group) — the group
+         * record itself is removed, the children are untouched. A no-op
+         * (returns `[]`) if `groupId` isn't a group.
+         */
+        ungroup(groupId: string): readonly string[];
+        /**
+         * Aligns every given object's matching edge/center to the corresponding
+         * edge/center of their combined bounding box, as one undoable step.
+         * `"top"`/`"bottom"` follow board space's Y-up convention (`"top"` is
+         * the larger Y). Ids that don't resolve, or resolve to a Group (which
+         * has no position of its own), are skipped. A no-op under 2 resolvable
+         * ids — there's nothing to align relative to.
+         */
+        align(ids: readonly string[], edge: "left" | "right" | "top" | "bottom" | "centerX" | "centerY"): void;
+        /**
+         * Spaces the middle objects' centers evenly between the first and last
+         * (sorted along `axis`), as one undoable step — the two endpoints don't
+         * move. Ids that don't resolve, or resolve to a Group, are skipped. A
+         * no-op under 3 resolvable ids — there's no "middle" to distribute.
+         */
+        distribute(ids: readonly string[], axis: "x" | "y"): void;
+        /**
+         * Snapshots `ids` (recursively expanded through any group, same as
+         * `duplicate`) into an internal in-memory clipboard — never
+         * `navigator.clipboard`, scoped to this one controller instance and
+         * replaced wholesale by the next `copy`/`cut`. Read-only; works even
+         * on a read-only board.
+         */
+        copy(ids: readonly string[]): void;
+        /** `copy`, then removes every resolved object (recursively through any group) as one undoable step. */
+        cut(ids: readonly string[]): void;
+        /**
+         * Clones the current clipboard contents onto the board as one undoable
+         * step, offset the same small cascade `duplicate` uses (no cursor
+         * position to paste relative to yet). Returns the new top-level ids —
+         * a pasted group's own id stands for its (also-pasted) children, which
+         * aren't listed separately. `[]` when the clipboard is empty.
+         */
+        paste(): readonly string[];
         table: {
             addRow(tableId: string): void;
             addCol(tableId: string): void;
@@ -1010,6 +1261,14 @@ interface BoardController {
         };
         select(ids: readonly string[]): void;
         import(document: SerializedBoardDocument): readonly string[];
+        /**
+         * Toggle lock state for the current selection (or focused note/text/
+         * table/image/timer), matching whatever a single Host lock/unlock
+         * control already does per object type. A no-op with nothing selected,
+         * on a headless board, or when every actionable target is locked by
+         * another collaborator who isn't the current lock holder.
+         */
+        toggleSelectionLock(): void;
     };
     readonly query: {
         get(id: string): DeepReadonly<BoardObject> | undefined;