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

package/dist/core.d.ts

@@ -181,6 +181,21 @@ interface CustomObjectDefinition<Props extends JsonValue = JsonValue> {
     /** One pure, synchronous step per consecutive schema version. */
     migrate?: Readonly<Record<number, (oldProps: JsonValue) => JsonValue>>;
     describe(object: ReadonlyCustomObject<Props>, context: ObjectDescribeContext): BoardScene;
+    /**
+     * Optional point-level hit-test precision (Phase 8). Every custom object
+     * hit-tests against its bounding box (`fallback.bounds`) by default — this
+     * lets a non-rectangular shape (e.g. a circular card, an L-shaped region)
+     * reject a point that's inside that box but outside its actual visible
+     * silhouette, tightening a click/marquee/raycast hit to the shape's real
+     * outline. `point` is in this object's own local space — the same
+     * untransformed space `describe`'s returned geometry already lives in
+     * (the caller inverse-transforms the pointer's board point through
+     * `object.transform` before calling this). Absent means every point
+     * inside the bounding box hits, matching pre-Phase-8 behavior exactly.
+     * Rejecting a point here does not fall through to whatever's underneath —
+     * the gesture simply misses this object, same as clicking empty space.
+     */
+    hitTest?(object: ReadonlyCustomObject<Props>, point: BoardPoint): boolean;
 }
 interface SceneNodeBase {
     key: string;
@@ -214,6 +229,15 @@ interface SceneGroup extends SceneNodeBase {
     kind: "group";
     children: readonly BoardScene[];
 }
+/**
+ * **No renderer or SVG-export interpreter exists for this node kind yet**
+ * (tracked as deferred work — see `renderer/shapes/customObjects.ts`'s
+ * `"path"` case). Returning a `ScenePath` from `describe()` renders nothing,
+ * exports nothing, and contributes no hit-test bounds — it neither errors
+ * nor emits a diagnostic. Until an interpreter ships, build custom shapes
+ * from `SceneRect`/`SceneEllipse`/`SceneGroup`/`SceneText`/`SceneImage`
+ * instead.
+ */
 interface ScenePath extends SceneNodeBase {
     kind: "path";
     /** SVG-style path data, board-local coordinates. */
@@ -386,8 +410,23 @@ declare function canUnlockItem(item: Lockable | undefined, userId: string | unde
 /** Wire fields for a locked item; omitted entirely when unlocked. */
 declare function serializeLock(item: Lockable): Lockable;
 
+/**
+ * Per-object visibility (Phase 8) — mirrors `itemLock.ts`'s `Lockable`
+ * pattern exactly, but simpler: unlike a lock, hidden state carries no
+ * holder/ownership concept, so there's no analogue to `LockHolder`/
+ * `canUnlockItem`. A hidden object stays fully present in the Document
+ * (still serializes, persists, syncs, undoes/redoes) — it just skips
+ * rendering and hit-testing/selection candidacy. `hidden` absent or
+ * `false` means visible; this keeps every pre-Phase-8 document (which has
+ * no `hidden` field on any object at all) implicitly fully visible with
+ * zero migration needed.
+ */
+interface Hideable {
+    hidden?: boolean;
+}
+
 /** A kitchen timer sitting on the board. Remaining time is derived, not ticked. */
-interface KitchenTimer extends Lockable {
+interface KitchenTimer extends Lockable, Hideable {
     id: string;
     x: number;
     y: number;
@@ -413,9 +452,25 @@ declare function setTimerDuration(timer: KitchenTimer, durationMs: number): Kitc
 declare function formatTimer(ms: number): string;
 
 declare const SHAPE_MIN_SIZE = 0.5;
-declare const SHAPE_DEFAULT_STROKE = "#1C1C1E";
-declare const SHAPE_DEFAULT_STROKE_WIDTH = 0.12;
-interface RectangleObject extends Lockable {
+/**
+ * Centralized shape style defaults (Phase 8) — one object a Host can read
+ * to know (or, by not relying on the standalone constants below, override
+ * via its own UI state) what a newly drawn Rectangle/Ellipse/Line/Arrow/
+ * Polygon/Star/Heart starts with when the user hasn't picked a stroke/width
+ * yet. `shapeTool.ts` (commit-time), `renderer/shapes/lines.ts` (render-time
+ * fallback for an object missing these fields), and
+ * `persistence/serialization/svg.ts` (export-time fallback) all read from
+ * here — the two standalone constants below are kept for source
+ * compatibility and simply mirror this object's values, not a second
+ * source of truth.
+ */
+declare const SHAPE_STYLE_DEFAULTS: {
+    readonly stroke: "#1C1C1E";
+    readonly strokeWidth: 0.12;
+};
+declare const SHAPE_DEFAULT_STROKE: "#1C1C1E";
+declare const SHAPE_DEFAULT_STROKE_WIDTH: 0.12;
+interface RectangleObject extends Lockable, Hideable {
     id: string;
     x: number;
     y: number;
@@ -437,7 +492,7 @@ interface RectangleObject extends Lockable {
      */
     rotation?: number;
 }
-interface EllipseObject extends Lockable {
+interface EllipseObject extends Lockable, Hideable {
     id: string;
     x: number;
     y: number;
@@ -455,7 +510,7 @@ declare function cloneRectangle(rect: RectangleObject): RectangleObject;
 declare function cloneEllipse(ellipse: EllipseObject): EllipseObject;
 /** `"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 {
+interface LineObject extends Lockable, Hideable {
     id: string;
     start: BoardPoint;
     end: BoardPoint;
@@ -463,7 +518,7 @@ interface LineObject extends Lockable {
     strokeWidth?: number;
     opacity?: number;
 }
-interface ArrowObject extends Lockable {
+interface ArrowObject extends Lockable, Hideable {
     id: string;
     start: BoardPoint;
     end: BoardPoint;
@@ -482,7 +537,7 @@ interface ArrowObject extends Lockable {
  * `polygonStartAngle`, which encodes each side count's own vertex
  * orientation so the outline always matches the legacy drag-preview shape.
  */
-interface PolygonObject extends Lockable {
+interface PolygonObject extends Lockable, Hideable {
     id: string;
     x: number;
     y: number;
@@ -498,7 +553,7 @@ interface PolygonObject extends Lockable {
 }
 declare function clonePolygon(polygon: PolygonObject): PolygonObject;
 /** 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 {
+interface StarObject extends Lockable, Hideable {
     id: string;
     x: number;
     y: number;
@@ -516,7 +571,7 @@ interface StarObject extends Lockable {
 }
 declare function cloneStar(star: StarObject): StarObject;
 /** 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 {
+interface HeartObject extends Lockable, Hideable {
     id: string;
     x: number;
     y: number;
@@ -544,7 +599,7 @@ declare function cloneArrow(arrow: ArrowObject): ArrowObject;
  * a group into its leaf members is always done by the caller (recursively,
  * with cycle protection), never assumed here.
  */
-interface GroupObject extends Lockable {
+interface GroupObject extends Lockable, Hideable {
     id: string;
     children: string[];
 }
@@ -570,7 +625,7 @@ interface StrokePoint extends BoardPoint {
  * geometric outline, not an expressive ink mark.
  */
 type StrokeTool = "marker" | "highlighter" | "shape";
-interface Stroke extends Lockable {
+interface Stroke extends Lockable, Hideable {
     id: string;
     color: string;
     baseWidth: number;
@@ -589,7 +644,7 @@ interface Stroke extends Lockable {
 declare const ERASE_THRESHOLD = 0.95;
 declare function cloneStroke(stroke: Stroke): Stroke;
 type SerializedPoint = [number, number, number, number];
-interface SerializedStroke extends Lockable {
+interface SerializedStroke extends Lockable, Hideable {
     id: string;
     color: string;
     baseWidth: number;
@@ -683,7 +738,7 @@ interface NoteVote {
  * A sticky note: content floating above the board at a z-offset (pillar 3 —
  * depth as an organizational axis). Center position in board space.
  */
-interface StickyNote extends Lockable {
+interface StickyNote extends Lockable, Hideable {
     id: string;
     x: number;
     y: number;
@@ -701,7 +756,7 @@ interface StickyNote extends Lockable {
  * top-left corner; lines flow downward (-y). Text joins the clustering
  * system like handwriting (build prompt §6.4).
  */
-interface TextBlock extends Lockable {
+interface TextBlock extends Lockable, Hideable {
     id: string;
     x: number;
     y: number;
@@ -731,7 +786,7 @@ declare function cloneNote(note: StickyNote): StickyNote;
  * Interactive structured table on the board. Position (x, y) is top-left in board units.
  * Cells are indexed as `${row},${col}` keys mapping to cell text content.
  */
-interface TableBlock extends Lockable {
+interface TableBlock extends Lockable, Hideable {
     id: string;
     x: number;
     y: number;
@@ -757,7 +812,7 @@ declare const FOG_COLOR = "#FFFFFF";
  * An imported image block on the board plane.
  * Coordinates (x, y) represent the center of the image in board space.
  */
-interface ImageBlock extends Lockable {
+interface ImageBlock extends Lockable, Hideable {
     id: string;
     /**
      * A legacy, read-only data URL (or, historically, an arbitrary string) —
@@ -807,6 +862,15 @@ type DocumentLoadResult = {
 declare function loadDocumentBytes(originalBytes: string): DocumentLoadResult;
 declare function migrateDocument(raw: unknown): DocumentLoadResult;
 declare function serializeDocument(document: unknown): string;
+/**
+ * A Document's serialized size in bytes (Phase 5) — UTF-8, not UTF-16
+ * `string.length`, since a Document with non-ASCII note/text content (most
+ * of them, eventually) would otherwise under-report. Useful for a Host
+ * deciding when to warn about an unusually large board, or for logging/
+ * telemetry around save size — not consulted by anything inside this
+ * package itself, which has no size limit of its own.
+ */
+declare function documentSize(document: CurrentSerializedDocument): number;
 
 interface SearchableComment {
     id: string;
@@ -1016,6 +1080,16 @@ declare class BoardDocument {
      * `getSelectedItemInfo`'s custom branch hardcodes `isLocked: false`).
      */
     isLocked(id: string): boolean;
+    /**
+     * True if `id` exists and is hidden, for any type — the same per-type
+     * probe pattern as {@link isLocked} (Phase 8). Custom objects are
+     * excluded for the same reason `isLocked` excludes them: they have no
+     * `Hideable` field at all, so "hidden" isn't a concept that applies to
+     * them yet. Used by marquee selection (`selectTool.ts`) to keep a hidden
+     * object out of a rubber-band selection even for object types whose own
+     * renderer doesn't yet suppress click-based hit-testing.
+     */
+    isHidden(id: string): boolean;
     subscribe(listener: Listener): () => void;
     addStrokes(strokes: Stroke[]): void;
     removeStrokes(ids: string[]): void;
@@ -1142,7 +1216,17 @@ declare class BoardDocument {
     static deserializeNotes(data: SerializedDocument): StickyNote[];
     static deserializeTexts(data: SerializedDocument): TextBlock[];
     static deserializeTables(data: SerializedDocument): TableBlock[];
-    static deserializeStrokes(data: SerializedDocument): Stroke[];
+    /**
+     * `onSkip` (Phase 9) replaces an unconditional `console.error` — `core`
+     * must never do raw console I/O (no dev-gate, no way for a Host to
+     * suppress or redirect it), so a skipped stroke is now reported only if
+     * the caller asks for it, via whatever diagnostic channel it already
+     * has (e.g. `controller-internal.ts` routes this into the same typed
+     * `"error"` event every other diagnostic already uses). Silent by
+     * default, matching how every other `deserialize*` method here already
+     * behaves (no diagnostics at all).
+     */
+    static deserializeStrokes(data: SerializedDocument, onSkip?: (id: string, cause: unknown) => void): Stroke[];
     /**
      * Every mutation funnels through here, so paint-order tracking lives in
      * exactly one place rather than at every individual add/remove call site
@@ -1153,17 +1237,18 @@ declare class BoardDocument {
      * ids already tracked (idempotent by construction: `orderIndex.has` gates
      * every append).
      *
-     * `orderChanged` is populated here whenever `objectOrder` actually
-     * changed — not just for an explicit reorder, but for any add/remove too.
-     * A pure append never shifts an existing id's rank (new ids land at the
-     * tail), but a removal splices a middle id out, which *does* shift every
-     * id after it down by one — a renderer that only resynced Z on an
-     * explicit reorder would silently render those with a stale rank until
-     * something else happened to touch them, eventually colliding with a
-     * freshly-added object's freshly-computed Z. Firing this on every
-     * order-touching change (not just removes) is simpler than special-
-     * casing which kind of change actually needs it, at the cost of a
-     * redundant same-value resync on a pure append.
+     * `orderChanged` (Phase 9) reports exactly the ids whose rank actually
+     * changed, using `orderIndex` throughout instead of `indexOf` — a pure
+     * append never shifts any existing id's rank (new ids land at the tail,
+     * already covered by this same change's own `Added` field, so
+     * `orderChanged` stays unset), while a removal shifts every id at-or-
+     * after the lowest removed rank down by one, computed in a single O(n)
+     * filter pass (not one `indexOf`+`splice` per removed id) regardless of
+     * how many ids this one change removes. Every renderer's `onChange` now
+     * looks up only the ids actually in `orderChanged` instead of walking
+     * its entire mesh map on any order-touching change — a broad, unfiltered
+     * `orderChanged` here would silently defeat that fix, not just waste
+     * cycles here.
      */
     private emit;
 }
@@ -1786,5 +1871,5 @@ type BoardStroke = Stroke;
 type SerializedBoardStroke = SerializedStroke;
 type SerializedBoardDocument = CurrentSerializedDocument;
 
-export { ASSET_CACHE_BYTES_DEFAULT, ASSET_CACHE_BYTES_MAX, ASSET_CACHE_BYTES_MIN, ASSET_EXPORT_MAX_DECODED_MEGAPIXELS, ASSET_EXPORT_MAX_ENCODED_BYTES, ASSET_MAX_CONCURRENT_RESOLUTIONS, ASSET_MAX_DECODED_MEGAPIXELS, ASSET_MAX_DIMENSION_PX, ASSET_MAX_ENCODED_BYTES, ASSET_REF_MAX_BYTES, ASSET_REF_PATTERN, AddArrowCommand, AddEllipseCommand, AddGroupCommand, AddHeartCommand, AddImageCommand, AddLineCommand, AddNoteCommand, AddPolygonCommand, AddRectangleCommand, AddStarCommand, AddStrokesCommand, AddTableCommand, AddTextCommand, AddTimerCommand, AssetResolutionError, BEACON_INSET, BoardDocument, CURRENT_DOCUMENT_SCHEMA_VERSION, ClusterStore, CommandBatch, DeleteArrowCommand, DeleteEllipseCommand, DeleteGroupCommand, DeleteHeartCommand, DeleteImageCommand, DeleteLineCommand, DeleteNoteCommand, DeletePolygonCommand, DeleteRectangleCommand, DeleteStarCommand, DeleteStrokesCommand, DeleteTableCommand, DeleteTextCommand, DeleteTimerCommand, DocumentRecoveryError, END_TAPER, ERASE_THRESHOLD, EraseCommand, FOG_COLOR, HIGHLIGHT_COLORS, History, IDENTITY, INK_COLORS, LockItemsCommand, MIN_WIDTH_FACTOR, NOTE_COLORS, NOTE_DEFAULT_SIZE, NOTE_DEFAULT_Z, NOTE_MAX_Z, NOTE_MIN_Z, NOTE_PEEL_STEP, ReorderObjectCommand, SDK_DEVELOPMENT_VERSION, SDK_PACKAGE_NAME, SHAPE_DEFAULT_STROKE, SHAPE_DEFAULT_STROKE_WIDTH, SHAPE_MIN_SIZE, STAMPS, STAMP_SIZE, SUPPORTED_ASSET_MEDIA_TYPES, SpatialIndex, TABLE_DEFAULT_CELL_HEIGHT, TABLE_DEFAULT_CELL_WIDTH, TABLE_DEFAULT_FONT_SIZE, TEXT_DEFAULT_SIZE, TIMER_DEFAULT_DURATION_MS, TIMER_DEFAULT_SIZE, TIMER_PRESETS_MS, TransformCommand, TransformObjectsCommand, UpdateArrowCommand, UpdateEllipseCommand, UpdateGroupCommand, UpdateHeartCommand, UpdateImageCommand, UpdateLineCommand, UpdateNoteCommand, UpdatePolygonCommand, UpdateRectangleCommand, UpdateStarCommand, UpdateTableCommand, UpdateTextCommand, UpdateTimerCommand, apply, applyItemLock, assetRef, avgScale, canUnlockItem, changeToOps, clampAssetCacheBytes, cloneArrow, cloneCustomObject, cloneEllipse, cloneGroup, cloneHeart, cloneImage, cloneLine, cloneNote, clonePolygon, cloneRectangle, cloneStar, cloneStroke, cloneTable, cloneText, cloneTimer, documentId, documentToSVG, formatTimer, invert, isAssetRef, isIdentity, isStampKind, loadDocumentBytes, measureTable, measureTextBlock, migrateDocument, mul, pauseTimer, placePresenceBeacon, ribbonEdges, rotationAbout, scalingAbout, searchBoard, serializeDocument, serializeLock, serializeStroke, setTimerDuration, stampDataUrl, startTimer, strokeId, timerExpired, timerRemaining, toggleTimer, translation };
+export { ASSET_CACHE_BYTES_DEFAULT, ASSET_CACHE_BYTES_MAX, ASSET_CACHE_BYTES_MIN, ASSET_EXPORT_MAX_DECODED_MEGAPIXELS, ASSET_EXPORT_MAX_ENCODED_BYTES, ASSET_MAX_CONCURRENT_RESOLUTIONS, ASSET_MAX_DECODED_MEGAPIXELS, ASSET_MAX_DIMENSION_PX, ASSET_MAX_ENCODED_BYTES, ASSET_REF_MAX_BYTES, ASSET_REF_PATTERN, AddArrowCommand, AddEllipseCommand, AddGroupCommand, AddHeartCommand, AddImageCommand, AddLineCommand, AddNoteCommand, AddPolygonCommand, AddRectangleCommand, AddStarCommand, AddStrokesCommand, AddTableCommand, AddTextCommand, AddTimerCommand, AssetResolutionError, BEACON_INSET, BoardDocument, CURRENT_DOCUMENT_SCHEMA_VERSION, ClusterStore, CommandBatch, DeleteArrowCommand, DeleteEllipseCommand, DeleteGroupCommand, DeleteHeartCommand, DeleteImageCommand, DeleteLineCommand, DeleteNoteCommand, DeletePolygonCommand, DeleteRectangleCommand, DeleteStarCommand, DeleteStrokesCommand, DeleteTableCommand, DeleteTextCommand, DeleteTimerCommand, DocumentRecoveryError, END_TAPER, ERASE_THRESHOLD, EraseCommand, FOG_COLOR, HIGHLIGHT_COLORS, History, IDENTITY, INK_COLORS, LockItemsCommand, MIN_WIDTH_FACTOR, NOTE_COLORS, NOTE_DEFAULT_SIZE, NOTE_DEFAULT_Z, NOTE_MAX_Z, NOTE_MIN_Z, NOTE_PEEL_STEP, ReorderObjectCommand, SDK_DEVELOPMENT_VERSION, SDK_PACKAGE_NAME, SHAPE_DEFAULT_STROKE, SHAPE_DEFAULT_STROKE_WIDTH, SHAPE_MIN_SIZE, SHAPE_STYLE_DEFAULTS, STAMPS, STAMP_SIZE, SUPPORTED_ASSET_MEDIA_TYPES, SpatialIndex, TABLE_DEFAULT_CELL_HEIGHT, TABLE_DEFAULT_CELL_WIDTH, TABLE_DEFAULT_FONT_SIZE, TEXT_DEFAULT_SIZE, TIMER_DEFAULT_DURATION_MS, TIMER_DEFAULT_SIZE, TIMER_PRESETS_MS, TransformCommand, TransformObjectsCommand, UpdateArrowCommand, UpdateEllipseCommand, UpdateGroupCommand, UpdateHeartCommand, UpdateImageCommand, UpdateLineCommand, UpdateNoteCommand, UpdatePolygonCommand, UpdateRectangleCommand, UpdateStarCommand, UpdateTableCommand, UpdateTextCommand, UpdateTimerCommand, apply, applyItemLock, assetRef, avgScale, canUnlockItem, changeToOps, clampAssetCacheBytes, cloneArrow, cloneCustomObject, cloneEllipse, cloneGroup, cloneHeart, cloneImage, cloneLine, cloneNote, clonePolygon, cloneRectangle, cloneStar, cloneStroke, cloneTable, cloneText, cloneTimer, documentId, documentSize, documentToSVG, formatTimer, invert, isAssetRef, isIdentity, isStampKind, loadDocumentBytes, measureTable, measureTextBlock, migrateDocument, mul, pauseTimer, placePresenceBeacon, ribbonEdges, rotationAbout, scalingAbout, searchBoard, serializeDocument, serializeLock, serializeStroke, setTimerDuration, stampDataUrl, startTimer, strokeId, timerExpired, timerRemaining, toggleTimer, translation };
 export type { ArrowHeadStyle, ArrowObject, AssetDiagnostic, AssetIngestRequest, AssetIngestResult, AssetIngestor, AssetKind, AssetPurpose, AssetRef, AssetResolutionErrorCode, AssetResolveRequest, AssetResolveResult, AssetResolver, BBox, BoardKeyInput, BoardPoint, BoardPointerInput, BoardScene, BoardStroke, ClusterIdFactory, Command, CommandKind, CurrentSerializedDocument, CurrentSerializedStroke, CustomBoardObject, CustomObjectAddInput, CustomObjectDefinition, CustomTool, CustomToolDefinition, DocumentChange, DocumentId, DocumentLoadResult, DocumentRecoveryCode, EllipseObject, ExtensionCommand, ExtensionDiagnostic, ExtensionHitResult, ExtensionId, ExtensionRequirement, GroupObject, HeartObject, ImageBlock, InputModifiers, JsonObject, JsonValue, KitchenTimer, LineObject, LockHolder, LockTarget, Lockable, Mat2x3, NoteVote, ObjectDescribeContext, ObjectIntent, ObjectType, Op, OpCollection, PolygonObject, PresencePlacement, QueryableBoardObject, ReadonlyCustomObject, RectangleObject, ReorderDirection, RibbonEdgePoint, SceneEllipse, SceneGroup, SceneImage, ScenePath, SceneRect, SceneText, ScrawlExtension, SearchHit, SearchHitKind, SearchableBoard, SearchableComment, SerializedBoardDocument, SerializedBoardStroke, SerializedPoint, SerializedStroke, StampKind, StarObject, StickyNote, Stroke, StrokeId, StrokePoint, StrokeTool, SupportedAssetMediaType, TableBlock, TextBlock, ToolCancelReason, ToolCapabilities, ToolCursor, ToolId, ViewportInset };