studiograph 1.3.48-next.26 → 1.3.48-next.261

package/dist/core/artifact-warnings.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Structural warnings for an artifact write (P4.3) — browser-free lints that let
+ * the agent self-verify what it just produced, in the SAME turn, without a
+ * Playwright render.
+ *
+ * Paired with the P4.2 frame manifest, these back the "return-rich" create/patch
+ * returns: `summarizeArtifactWrite` hands both surfaces (agent chat + MCP) ONE
+ * identical `{ manifest, warnings }` payload so the two can't drift. The manifest
+ * is built WITHOUT a `frameId`, so it carries no per-frame `content` — the return
+ * is structure-only and safe to persist across turns (it does NOT trip the
+ * `compactArtifactHistory` MUST-NOT-PERSIST rule that elides full artifact source).
+ *
+ * The lints are deliberately conservative — high precision over recall — so a
+ * legitimate single-`app` artifact is never nagged into being split:
+ *   - `packed-slides`  — ONE non-deck frame whose content carries the fingerprints
+ *                        of a hand-rolled DECK (the agent freelancing a stepper
+ *                        inside one frame instead of one frame per slide).
+ *   - `packed-pages`   — ONE non-document frame whose content carries the
+ *                        fingerprints of a hand-rolled multi-page DOCUMENT (forced
+ *                        page breaks or a page-column grid, e.g. the observed
+ *                        `app` frame with a `repeat(var(--page-cols),816px)` grid)
+ *                        instead of a `pages` frame the platform paginates.
+ *   - `empty-frame`    — a frame that will render blank (objective).
+ *   - `near-byte-cap`  — the bundle is close to the 512KB ceiling, so the NEXT
+ *                        edit may be rejected (objective).
+ */
+import { type ArtifactBundle } from './artifact-frame-model.js';
+import { type ArtifactManifest } from './artifact-manifest.js';
+export type ArtifactWarningCode = 'packed-slides' | 'packed-pages' | 'empty-frame' | 'near-byte-cap';
+export interface ArtifactWarning {
+    code: ArtifactWarningCode;
+    message: string;
+    /** Present for frame-scoped warnings (`empty-frame`, `packed-slides`, `packed-pages`). */
+    frameId?: string;
+}
+/**
+ * Compute the structural warnings for a (already-validated) bundle. Pure — no IO,
+ * no browser. Order: the headline adherence lint first, then per-frame blanks,
+ * then the size ceiling.
+ */
+export declare function artifactStructuralWarnings(bundle: ArtifactBundle): ArtifactWarning[];
+/**
+ * THE return-rich payload both write surfaces attach to a create/patch result:
+ * the structural manifest (P4.2) + the lints. Built from the WRITTEN bundle so it
+ * reflects exactly what was persisted. The manifest carries no per-frame
+ * `content` (no `frameId` option) → the result is structure-only and persist-safe.
+ */
+export declare function summarizeArtifactWrite(bundle: ArtifactBundle): {
+    manifest: ArtifactManifest;
+    warnings: ArtifactWarning[];
+};

package/dist/core/artifact-warnings.js

@@ -0,0 +1,165 @@
+/**
+ * Structural warnings for an artifact write (P4.3) — browser-free lints that let
+ * the agent self-verify what it just produced, in the SAME turn, without a
+ * Playwright render.
+ *
+ * Paired with the P4.2 frame manifest, these back the "return-rich" create/patch
+ * returns: `summarizeArtifactWrite` hands both surfaces (agent chat + MCP) ONE
+ * identical `{ manifest, warnings }` payload so the two can't drift. The manifest
+ * is built WITHOUT a `frameId`, so it carries no per-frame `content` — the return
+ * is structure-only and safe to persist across turns (it does NOT trip the
+ * `compactArtifactHistory` MUST-NOT-PERSIST rule that elides full artifact source).
+ *
+ * The lints are deliberately conservative — high precision over recall — so a
+ * legitimate single-`app` artifact is never nagged into being split:
+ *   - `packed-slides`  — ONE non-deck frame whose content carries the fingerprints
+ *                        of a hand-rolled DECK (the agent freelancing a stepper
+ *                        inside one frame instead of one frame per slide).
+ *   - `packed-pages`   — ONE non-document frame whose content carries the
+ *                        fingerprints of a hand-rolled multi-page DOCUMENT (forced
+ *                        page breaks or a page-column grid, e.g. the observed
+ *                        `app` frame with a `repeat(var(--page-cols),816px)` grid)
+ *                        instead of a `pages` frame the platform paginates.
+ *   - `empty-frame`    — a frame that will render blank (objective).
+ *   - `near-byte-cap`  — the bundle is close to the 512KB ceiling, so the NEXT
+ *                        edit may be rejected (objective).
+ */
+import { ARTIFACT_BUNDLE_MAX_BYTES, } from './artifact-frame-model.js';
+import { buildArtifactManifest } from './artifact-manifest.js';
+/** Fraction of the hard byte cap at which `near-byte-cap` starts warning. */
+const NEAR_CAP_FRACTION = 0.9;
+/** `data-artifact-frame` is the PLATFORM's own frame-splitting attribute — a
+ *  single authored frame should never contain it. Two or more inside ONE frame's
+ *  content means the agent hand-declared multiple frames in one (the exact
+ *  hand-rolled-deck failure `packed-slides` exists to catch). */
+const PACKED_SUBFRAME_THRESHOLD = 2;
+/** ...or this many FORCED page breaks: a multi-page document crammed into a
+ *  non-`pages` frame instead of authored as a paginating `pages` frame. */
+const PACKED_PAGEBREAK_THRESHOLD = 2;
+/** Bound the regex scans so a pathological multi-hundred-KB frame can't stall the
+ *  event loop (mirrors artifact-manifest's KEY_TEXT_SCAN_LIMIT rationale). A cut
+ *  match can only UNDERcount → at worst a missed warning, never a false positive. */
+const PACKED_SCAN_LIMIT = 64 * 1024;
+/** Forced page break, old (`page-break-before:always`) and modern
+ *  (`break-before:page`) syntax — the fingerprint of paginating by hand. */
+const PAGE_BREAK_RE = /(?:page-break-(?:before|after)\s*:\s*always|break-(?:before|after)\s*:\s*page)/gi;
+/** A MULTI-page CSS variable — `--page-cols`, `--page-count`, etc. The observed
+ *  bug grid was `grid-template-columns: repeat(var(--page-cols),816px)`; a var that
+ *  names a page COUNT/COLUMN only exists to fake a multi-page grid. Deliberately
+ *  excludes the SINGULAR `--page-width`/`--page-height`/`--page-size` (a legit
+ *  single content column declares its own page dimensions) and `--page-color`
+ *  (the `\b` after the keyword guards it). */
+const PAGE_COLUMN_VAR_RE = /--page-(?:col|cols|count|num)\b/i;
+/** ...or a `repeat()` whose track is a BARE page-width px literal
+ *  (US-Letter/A4/Legal @96dpi) directly after a count of TWO OR MORE — `repeat(3,
+ *  816px)`, the shape of a hand-built MULTI-page-column grid. Kept tight for
+ *  precision: the count must be ≥2 (or `auto-fill`/`auto-fit`) so a single
+ *  page-width content column `repeat(1, 816px)` does NOT match; the page literal
+ *  must follow the comma with a left boundary, so a card grid whose track is
+ *  `minmax(1056px, 1fr)` (the literal is nested, not bare) does NOT match, and
+ *  `21056px` does not match `1056`. The `repeat(var(--page-cols),816px)` form is
+ *  caught by PAGE_COLUMN_VAR_RE instead. */
+const PAGE_COLUMN_GRID_RE = /repeat\(\s*(?:[2-9]|\d{2,}|auto-fill|auto-fit)\s*,\s*(?:816|1056|794|1123|1344)px\b/i;
+function byteSizeOf(bundle) {
+    // Compact JSON — byte-identical to validateArtifactBundle's cap measurement, so
+    // the advisory tracks the exact ceiling the next edit's validator enforces.
+    return new TextEncoder().encode(JSON.stringify(bundle)).length;
+}
+function countMatches(text, re) {
+    const matches = text.match(re);
+    return matches ? matches.length : 0;
+}
+/**
+ * Classify a SINGLE non-deck/non-document frame whose content looks like a deck or
+ * a multi-page document hand-rolled inside one frame. High precision over recall
+ * (the founder's explicit priority): only the unambiguous fingerprints, NOT signals
+ * a legitimate single-`app` artifact uses for its own reasons — a `.slide` class
+ * (image carousels), repeated `height:100vh` (landing-page sections), or a plain
+ * `repeat(3,1fr)` card grid are common in real apps, so they are NOT counted.
+ *
+ * Returns the kind of artifact the frame is impersonating, or null. `pages` is
+ * checked first: a forced-page-break / page-grid document is the headline observed
+ * bug, and it can also carry stray `data-artifact-frame` markers.
+ */
+function packedKind(frame) {
+    if (frame.layout !== 'app' && frame.layout !== 'artboard')
+        return null;
+    const scan = frame.content.length > PACKED_SCAN_LIMIT
+        ? frame.content.slice(0, PACKED_SCAN_LIMIT)
+        : frame.content;
+    // pages: a multi-page document faked inside one frame.
+    if (countMatches(scan, PAGE_BREAK_RE) >= PACKED_PAGEBREAK_THRESHOLD)
+        return 'pages';
+    if (PAGE_COLUMN_VAR_RE.test(scan) || PAGE_COLUMN_GRID_RE.test(scan))
+        return 'pages';
+    // slides: the platform frame-splitter attribute hand-declared multiple times.
+    if (countMatches(scan, /data-artifact-frame/gi) >= PACKED_SUBFRAME_THRESHOLD)
+        return 'slides';
+    return null;
+}
+/**
+ * Compute the structural warnings for a (already-validated) bundle. Pure — no IO,
+ * no browser. Order: the headline adherence lint first, then per-frame blanks,
+ * then the size ceiling.
+ */
+export function artifactStructuralWarnings(bundle) {
+    const warnings = [];
+    // packed-slides / packed-pages: only a SINGLE frame can be "a deck/document
+    // crammed into one frame"; a real multi-frame artifact is already doing the
+    // right thing.
+    if (bundle.frames.length === 1) {
+        const only = bundle.frames[0];
+        const kind = packedKind(only);
+        if (kind === 'slides') {
+            warnings.push({
+                code: 'packed-slides',
+                frameId: only.id,
+                message: `This is a single "${only.layout}" frame but its content looks like multiple slides. `
+                    + 'If you meant a deck, author one "slides" frame per slide so the platform steps, '
+                    + 'arranges, and exports them — do not hand-roll a stepper/filmstrip inside one frame.',
+            });
+        }
+        else if (kind === 'pages') {
+            warnings.push({
+                code: 'packed-pages',
+                frameId: only.id,
+                message: `This is a single "${only.layout}" frame but its content looks like a multi-page document `
+                    + '(forced page breaks or a page-column grid). Author a "pages" frame (a fixed page box, '
+                    + 'e.g. 816×1056 US-Letter) holding the document body and let the platform paginate, number, '
+                    + 'and PDF-scroll it — do not build your own page grid or page breaks inside an app/artboard frame.',
+            });
+        }
+    }
+    bundle.frames.forEach((frame, index) => {
+        if (frame.content.trim().length === 0) {
+            warnings.push({
+                code: 'empty-frame',
+                frameId: frame.id,
+                message: `Frame "${frame.id}" (index ${index}) has no content — it will render blank.`,
+            });
+        }
+    });
+    const byteSize = byteSizeOf(bundle);
+    if (byteSize > NEAR_CAP_FRACTION * ARTIFACT_BUNDLE_MAX_BYTES) {
+        const kb = Math.round(byteSize / 1024);
+        const capKb = Math.round(ARTIFACT_BUNDLE_MAX_BYTES / 1024);
+        warnings.push({
+            code: 'near-byte-cap',
+            message: `Bundle is ${kb}KB, near the ${capKb}KB limit — the next edit may be rejected; split or trim content.`,
+        });
+    }
+    return warnings;
+}
+/**
+ * THE return-rich payload both write surfaces attach to a create/patch result:
+ * the structural manifest (P4.2) + the lints. Built from the WRITTEN bundle so it
+ * reflects exactly what was persisted. The manifest carries no per-frame
+ * `content` (no `frameId` option) → the result is structure-only and persist-safe.
+ */
+export function summarizeArtifactWrite(bundle) {
+    return {
+        manifest: buildArtifactManifest(bundle),
+        warnings: artifactStructuralWarnings(bundle),
+    };
+}
+//# sourceMappingURL=artifact-warnings.js.map

package/dist/core/artifact-warnings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-warnings.js","sourceRoot":"","sources":["../../src/core/artifact-warnings.ts"],"names":[],"mappings":"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"}

package/dist/core/breakpoints.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Canonical responsive breakpoint queries — the single source of truth for
+ * BOTH CSS and JS so they can never drift.
+ *
+ *  - CSS consumes the same strings as `@custom-media --mobile / --touch`,
+ *    declared in `web/src/styles/media.css` (for component <style> blocks, via
+ *    @csstools/postcss-global-data) AND in-file at the top of `web/src/app.css`
+ *    (for the Tailwind/lightningcss pass — see the plan's build-pipeline note).
+ *  - JS consumes them via `matchMedia(MOBILE_MEDIA_QUERY)` and Svelte 5
+ *    `new MediaQuery(MOBILE_MEDIA_QUERY)`. Web code imports through the
+ *    `@core/breakpoints` alias.
+ *
+ * `src/core/__tests__/breakpoints-sync.test.ts` asserts all three CSS copies
+ * stay byte-identical to these constants.
+ *
+ * --mobile = LAYOUT TOPOLOGY (drawers vs docked). Primary `pointer: coarse`, so
+ * a keyboard-attached iPad (trackpad primary) reads as desktop. `767.98px` (not
+ * 768) dodges the exact overlap with Tailwind's `md` = min-width:768 and keeps a
+ * classic 768px iPad on desktop. The `max-height: 500px` arm catches landscape
+ * phones (≤~480 tall) while letting short tablets (≥600) fall through to desktop.
+ *
+ * --touch = TOUCH ERGONOMICS (44px tap targets, 16px inputs to dodge iOS focus
+ * auto-zoom). `any-pointer: coarse` so a touch device still counts even when its
+ * PRIMARY pointer is a trackpad (keyboard-attached iPad).
+ */
+export declare const MOBILE_MEDIA_QUERY = "(max-width: 767.98px), (hover: none) and (pointer: coarse) and (max-height: 500px)";
+export declare const TOUCH_MEDIA_QUERY = "(any-pointer: coarse)";

package/dist/core/breakpoints.js

@@ -0,0 +1,28 @@
+/**
+ * Canonical responsive breakpoint queries — the single source of truth for
+ * BOTH CSS and JS so they can never drift.
+ *
+ *  - CSS consumes the same strings as `@custom-media --mobile / --touch`,
+ *    declared in `web/src/styles/media.css` (for component <style> blocks, via
+ *    @csstools/postcss-global-data) AND in-file at the top of `web/src/app.css`
+ *    (for the Tailwind/lightningcss pass — see the plan's build-pipeline note).
+ *  - JS consumes them via `matchMedia(MOBILE_MEDIA_QUERY)` and Svelte 5
+ *    `new MediaQuery(MOBILE_MEDIA_QUERY)`. Web code imports through the
+ *    `@core/breakpoints` alias.
+ *
+ * `src/core/__tests__/breakpoints-sync.test.ts` asserts all three CSS copies
+ * stay byte-identical to these constants.
+ *
+ * --mobile = LAYOUT TOPOLOGY (drawers vs docked). Primary `pointer: coarse`, so
+ * a keyboard-attached iPad (trackpad primary) reads as desktop. `767.98px` (not
+ * 768) dodges the exact overlap with Tailwind's `md` = min-width:768 and keeps a
+ * classic 768px iPad on desktop. The `max-height: 500px` arm catches landscape
+ * phones (≤~480 tall) while letting short tablets (≥600) fall through to desktop.
+ *
+ * --touch = TOUCH ERGONOMICS (44px tap targets, 16px inputs to dodge iOS focus
+ * auto-zoom). `any-pointer: coarse` so a touch device still counts even when its
+ * PRIMARY pointer is a trackpad (keyboard-attached iPad).
+ */
+export const MOBILE_MEDIA_QUERY = '(max-width: 767.98px), (hover: none) and (pointer: coarse) and (max-height: 500px)';
+export const TOUCH_MEDIA_QUERY = '(any-pointer: coarse)';
+//# sourceMappingURL=breakpoints.js.map

package/dist/core/breakpoints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"breakpoints.js","sourceRoot":"","sources":["../../src/core/breakpoints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAC9B,oFAAoF,CAAC;AAEtF,MAAM,CAAC,MAAM,iBAAiB,GAAG,uBAAuB,CAAC"}

package/dist/core/cell-anchor.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Server-side validation for dataset cell-anchored comments.
+ *
+ * The full anchor model + the (pure, client-side) resolver live in the web
+ * app at `web/src/lib/utils/cell-anchor.ts` — resolution recomputes
+ * `{row, col}` against the live grid on every render and never runs on the
+ * server. The server's only job is to guard the write path: a cell comment
+ * stores its anchor JSON in the existing `anchor_relpos` column, so we must
+ * make sure (a) only datasets receive cell (JSON) anchors and (b) the JSON is
+ * structurally well-formed, so a markdown comment's base64 relpos is never
+ * confused for a cell anchor and a cell anchor is never fed to the text
+ * resolver. The two copies are intentionally small and independent (the web
+ * app does not import from `src/`).
+ */
+export interface CellAnchor {
+    kind: 'cell';
+    /** The commented row's cells at creation; absent when the snapshot was
+     *  dropped to fit `MAX_ANCHOR_RELPOS_LENGTH` (rowHash fallback). */
+    rowCells?: string[];
+    rowHash: string;
+    columnIndex: number;
+    headerName: string;
+}
+/** Cheap discriminator: a cell anchor is JSON (`{…}`); a markdown comment's
+ *  anchor is a base64 relpos blob, which never starts with `{`. */
+export declare function looksLikeCellAnchor(relpos: string | null | undefined): boolean;
+export declare function isValidCellAnchor(value: unknown): value is CellAnchor;
+/** Parse + validate a stored anchor string as a cell anchor, or null. */
+export declare function parseCellAnchor(relpos: string | null | undefined): CellAnchor | null;

package/dist/core/cell-anchor.js

@@ -0,0 +1,53 @@
+/**
+ * Server-side validation for dataset cell-anchored comments.
+ *
+ * The full anchor model + the (pure, client-side) resolver live in the web
+ * app at `web/src/lib/utils/cell-anchor.ts` — resolution recomputes
+ * `{row, col}` against the live grid on every render and never runs on the
+ * server. The server's only job is to guard the write path: a cell comment
+ * stores its anchor JSON in the existing `anchor_relpos` column, so we must
+ * make sure (a) only datasets receive cell (JSON) anchors and (b) the JSON is
+ * structurally well-formed, so a markdown comment's base64 relpos is never
+ * confused for a cell anchor and a cell anchor is never fed to the text
+ * resolver. The two copies are intentionally small and independent (the web
+ * app does not import from `src/`).
+ */
+/** Cheap discriminator: a cell anchor is JSON (`{…}`); a markdown comment's
+ *  anchor is a base64 relpos blob, which never starts with `{`. */
+export function looksLikeCellAnchor(relpos) {
+    return !!relpos && relpos[0] === '{';
+}
+export function isValidCellAnchor(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const a = value;
+    if (a.kind !== 'cell')
+        return false;
+    if (typeof a.rowHash !== 'string' || a.rowHash.length === 0)
+        return false;
+    if (typeof a.columnIndex !== 'number' || !Number.isInteger(a.columnIndex) || a.columnIndex < 0)
+        return false;
+    if (typeof a.headerName !== 'string')
+        return false;
+    if (a.rowCells !== undefined) {
+        if (!Array.isArray(a.rowCells))
+            return false;
+        if (!a.rowCells.every((c) => typeof c === 'string'))
+            return false;
+    }
+    return true;
+}
+/** Parse + validate a stored anchor string as a cell anchor, or null. */
+export function parseCellAnchor(relpos) {
+    if (!looksLikeCellAnchor(relpos))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(relpos);
+    }
+    catch {
+        return null;
+    }
+    return isValidCellAnchor(parsed) ? parsed : null;
+}
+//# sourceMappingURL=cell-anchor.js.map

package/dist/core/cell-anchor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cell-anchor.js","sourceRoot":"","sources":["../../src/core/cell-anchor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAYH;mEACmE;AACnE,MAAM,UAAU,mBAAmB,CAAC,MAAiC;IACpE,OAAO,CAAC,CAAC,MAAM,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC;AACtC,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC/C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM;QAAE,OAAO,KAAK,CAAC;IACpC,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,IAAI,CAAC,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC1E,IAAI,OAAO,CAAC,CAAC,WAAW,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,WAAW,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IAC7G,IAAI,OAAO,CAAC,CAAC,UAAU,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACnD,IAAI,CAAC,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC9B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC;YAAE,OAAO,KAAK,CAAC;QAC7C,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC;YAAE,OAAO,KAAK,CAAC;IACnE,CAAC;IACD,OAAO,IAAI,CAAC;AACb,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,eAAe,CAAC,MAAiC;IAChE,IAAI,CAAC,mBAAmB,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IAC9C,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACJ,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAgB,CAAC,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,IAAI,CAAC;IACb,CAAC;IACD,OAAO,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AAClD,CAAC"}

package/dist/core/comment-anchor.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Yjs-native anchor serialization for span-anchored comments.
+ *
+ * Anchors are pairs of `Y.RelativePosition` objects pointing at the start
+ * and end of the comment’s target span. RelativePosition is symbolic
+ * (“between these two Yjs items”) rather than offset-based, so it survives
+ * concurrent edits automatically — that’s the whole reason we built on Yjs
+ * for the editor. Comments survive other users typing in front of the
+ * highlighted span, surrounding deletes, or remote rewrites, with no
+ * server-side migration logic.
+ *
+ * Wire format:
+ *   2 bytes (big-endian)  — length of start blob
+ *   start blob            — Y.encodeRelativePosition output
+ *   end blob              — Y.encodeRelativePosition output
+ *   ↓ base64-encoded for SQLite blob storage / JSON transport
+ *
+ * Resolution falls back to fuzzy-quote matching when the primary anchor
+ * resolves to null AND the original highlighted text still exists exactly
+ * once in the document — Google Docs / Hypothesis pattern. If both fail,
+ * the comment renders as orphaned with the preserved quote as context.
+ */
+import * as Y from 'yjs';
+export interface SerializedAnchor {
+    /** Base64-encoded blob for the API. */
+    relpos: string;
+    /** Original highlighted text, ≤256 chars. Falls back to “” for empty selections. */
+    quote: string;
+}
+export interface ResolvedAnchor {
+    /** Inclusive absolute offset within the live Y.Text. */
+    from: number;
+    /** Exclusive absolute offset within the live Y.Text. */
+    to: number;
+    /** True iff the Yjs RelativePosition could not resolve AND quote-fallback also failed. */
+    orphaned: boolean;
+    /** True iff the primary RelativePosition failed but the quote was found exactly once. */
+    recovered: boolean;
+}
+export declare function serializeAnchor(ytext: Y.Text, from: number, to: number): SerializedAnchor;
+export declare function resolveAnchor(ydoc: Y.Doc, ytext: Y.Text, relposBase64: string, quote: string): ResolvedAnchor;

package/dist/core/comment-anchor.js

@@ -0,0 +1,147 @@
+/**
+ * Yjs-native anchor serialization for span-anchored comments.
+ *
+ * Anchors are pairs of `Y.RelativePosition` objects pointing at the start
+ * and end of the comment’s target span. RelativePosition is symbolic
+ * (“between these two Yjs items”) rather than offset-based, so it survives
+ * concurrent edits automatically — that’s the whole reason we built on Yjs
+ * for the editor. Comments survive other users typing in front of the
+ * highlighted span, surrounding deletes, or remote rewrites, with no
+ * server-side migration logic.
+ *
+ * Wire format:
+ *   2 bytes (big-endian)  — length of start blob
+ *   start blob            — Y.encodeRelativePosition output
+ *   end blob              — Y.encodeRelativePosition output
+ *   ↓ base64-encoded for SQLite blob storage / JSON transport
+ *
+ * Resolution falls back to fuzzy-quote matching when the primary anchor
+ * resolves to null AND the original highlighted text still exists exactly
+ * once in the document — Google Docs / Hypothesis pattern. If both fail,
+ * the comment renders as orphaned with the preserved quote as context.
+ */
+import * as Y from 'yjs';
+/**
+ * Encode a Uint8Array as base64. Uses Node's Buffer when available so
+ * server-side callers (MCP virtual-entity adapter, agent context builder)
+ * round-trip byte-identical to the browser path; falls back to btoa for
+ * pure-browser builds. Both halves must agree because anchors travel
+ * through the JSON wire format and back.
+ */
+function bytesToBase64(bytes) {
+    if (typeof Buffer !== 'undefined') {
+        return Buffer.from(bytes).toString('base64');
+    }
+    let s = '';
+    for (let i = 0; i < bytes.length; i++)
+        s += String.fromCharCode(bytes[i]);
+    return btoa(s);
+}
+function base64ToBytes(b64) {
+    if (typeof Buffer !== 'undefined') {
+        const buf = Buffer.from(b64, 'base64');
+        return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+    }
+    const s = atob(b64);
+    const out = new Uint8Array(s.length);
+    for (let i = 0; i < s.length; i++)
+        out[i] = s.charCodeAt(i);
+    return out;
+}
+export function serializeAnchor(ytext, from, to) {
+    const fromRel = Y.createRelativePositionFromTypeIndex(ytext, from);
+    const toRel = Y.createRelativePositionFromTypeIndex(ytext, to);
+    const startBytes = Y.encodeRelativePosition(fromRel);
+    const endBytes = Y.encodeRelativePosition(toRel);
+    const wire = new Uint8Array(2 + startBytes.length + endBytes.length);
+    const len = startBytes.length;
+    wire[0] = (len >> 8) & 0xff;
+    wire[1] = len & 0xff;
+    wire.set(startBytes, 2);
+    wire.set(endBytes, 2 + len);
+    const quote = ytext.toString().slice(from, to).slice(0, 256);
+    return { relpos: bytesToBase64(wire), quote };
+}
+export function resolveAnchor(ydoc, ytext, relposBase64, quote) {
+    try {
+        const wire = base64ToBytes(relposBase64);
+        const startLen = (wire[0] << 8) | wire[1];
+        const startBytes = wire.slice(2, 2 + startLen);
+        const endBytes = wire.slice(2 + startLen);
+        const fromRel = Y.decodeRelativePosition(startBytes);
+        const toRel = Y.decodeRelativePosition(endBytes);
+        const fromAbs = Y.createAbsolutePositionFromRelativePosition(fromRel, ydoc);
+        const toAbs = Y.createAbsolutePositionFromRelativePosition(toRel, ydoc);
+        if (fromAbs && toAbs && fromAbs.type === ytext && toAbs.type === ytext && fromAbs.index <= toAbs.index) {
+            // Yjs RelativePositions don’t return null when the items they
+            // reference are gone — they snap to a surviving item (often
+            // position 0 or the doc end), producing a degenerate
+            // from===to resolution. When the original anchor had
+            // non-empty content, a zero-width result means the anchor
+            // is stale, not literally degenerate; fall through to the
+            // quote-fallback. We accept from===to only when the original
+            // quote was also empty (entry-level anchors aren’t issued
+            // with an empty selection by the rail UI but the serializer
+            // permits it structurally).
+            const degenerate = fromAbs.index === toAbs.index && quote.length > 0;
+            if (!degenerate) {
+                // Even when both endpoints resolve to a non-degenerate range,
+                // Yjs may snap to surviving items that flank a deleted middle —
+                // the range exists but no longer covers the quoted text.
+                // Heuristic: when the resolved range is materially shorter than
+                // the quote, treat as drift and fall through to quote-fallback.
+                // (Pure insertion inside the anchor EXPANDS the range, so a
+                // longer-than-quote resolved range is the expected case and
+                // must still be accepted.) Threshold: resolved must be at
+                // least 50% of the quote length (min 1) — catches
+                // most-of-content-deleted while leaving normal edits alone.
+                if (quote.length > 0) {
+                    const resolvedLen = toAbs.index - fromAbs.index;
+                    const minLen = Math.max(1, Math.floor(quote.length * 0.5));
+                    if (resolvedLen < minLen) {
+                        // Drift — but if the surviving range is a clean prefix or
+                        // suffix of the original quote, the edit just lopped off
+                        // one end and the resolved range still points exactly
+                        // where the comment belongs (just shorter). Accept it as
+                        // a partial resolution. Middle-collapse cases produce
+                        // resolved text that's neither a prefix nor suffix of the
+                        // quote (e.g. anchor "quick brown fox" with the middle
+                        // deleted resolves to "qx" — not a prefix of the quote)
+                        // and still fall through to quote-fallback → orphan.
+                        const resolvedText = ytext.toString().slice(fromAbs.index, toAbs.index);
+                        if (quote.startsWith(resolvedText) || quote.endsWith(resolvedText)) {
+                            return { from: fromAbs.index, to: toAbs.index, orphaned: false, recovered: true };
+                        }
+                        // else: real drift — fall through to quote-fallback below.
+                    }
+                    else {
+                        return { from: fromAbs.index, to: toAbs.index, orphaned: false, recovered: false };
+                    }
+                }
+                else {
+                    return { from: fromAbs.index, to: toAbs.index, orphaned: false, recovered: false };
+                }
+            }
+        }
+    }
+    catch {
+        // fall through to quote-fallback
+    }
+    // Primary anchor failed. If the quote is still findable exactly once,
+    // re-anchor onto that occurrence. Multiple occurrences are ambiguous —
+    // we treat that as orphan to avoid silently picking the wrong instance.
+    if (quote.length > 0) {
+        const doc = ytext.toString();
+        const first = doc.indexOf(quote);
+        if (first >= 0 && doc.indexOf(quote, first + 1) < 0) {
+            return {
+                from: first,
+                to: first + quote.length,
+                orphaned: false,
+                recovered: true,
+            };
+        }
+    }
+    return { from: -1, to: -1, orphaned: true, recovered: false };
+}
+//# sourceMappingURL=comment-anchor.js.map

package/dist/core/comment-anchor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"comment-anchor.js","sourceRoot":"","sources":["../../src/core/comment-anchor.ts"],"names":[],"mappings":"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"}

package/dist/core/commit-messages.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Human-readable commit messages for entity + folder mutations.
+ *
+ * These strings are display-only — nothing parses them for behavior. Restore
+ * keys off the commit hash + the entity from the request, and the audit log
+ * only records the string. They surface in `git log`, the audit log, MCP file
+ * history, and any future cross-entity history view, where the entity name +
+ * type IS the useful context.
+ *
+ * The per-entity History panel renders its own change summary (computed from
+ * the file diff) and does NOT show these messages, so we optimize purely for
+ * how they read in a flat log.
+ *
+ * Format decisions:
+ *  - Past tense ("Created", "Edited", "Moved") — it's a log of what happened.
+ *  - `"Display Title" (Type)` — the title in quotes, the friendly type in parens.
+ *  - Batches enumerate up to 3 names + "(+N more)".
+ */
+/**
+ * Title-case an internal type key for display:
+ *   "deal" → "Deal", "meeting_note" → "Meeting Note".
+ * Built-in types have no stored label, so this is their friendly name.
+ */
+export declare function titleCaseType(type: string): string;
+export interface EntityRef {
+    /** Friendly type label, already resolved (e.g. "Deal"). */
+    typeLabel: string;
+    /** Display title (frontmatter `name`). Falls back to `id` when absent. */
+    title?: string | null;
+    /** Slug id — the fallback when there's no title. */
+    id: string;
+}
+/** `"Acme Corp Redesign" (Deal)` */
+export declare function entityLabel(ref: EntityRef): string;
+export declare const commitMessage: {
+    created: (ref: EntityRef) => string;
+    edited: (ref: EntityRef) => string;
+    editedBatch: (refs: EntityRef[]) => string;
+    deleted: (ref: EntityRef) => string;
+    deletedBatch: (refs: EntityRef[]) => string;
+    /** Rename changes the slug id; the title may be unchanged, so show the ids. */
+    renamed: (typeLabel: string, oldId: string, newId: string) => string;
+    changedType: (ref: EntityRef, fromLabel: string, toLabel: string) => string;
+    /** `folder` is the destination path display, or "(root)" for the repo root. */
+    movedTo: (ref: EntityRef, folder: string) => string;
+    /** Bulk move: count + destination reads cleaner than enumerate + target. */
+    movedBatch: (count: number, where: string) => string;
+    receivedBatch: (count: number, fromRepo: string) => string;
+    restored: (ref: EntityRef, shortHash: string) => string;
+    relinked: (oldId: string, newId: string) => string;
+    folderCreated: (path: string) => string;
+    folderRenamed: (from: string, to: string) => string;
+    folderDisplayRenamed: (path: string) => string;
+    folderDeleted: (path: string) => string;
+    folderMoved: (from: string, toRepo: string, to: string) => string;
+    folderReceived: (fromRepo: string, from: string, to: string) => string;
+};