@sobree/core 0.1.0

package/dist/ydoc/seed.d.ts

@@ -0,0 +1,45 @@
+import { Block, Paragraph, SobreeDocument } from '../doc/types';
+import * as Y from "yjs";
+/**
+ * Populate a fresh (or reset) Y.Doc with the contents of a SobreeDocument.
+ *
+ * Caller supplies the parallel `ids` array — these become the stable
+ * block ids stored in each block's Y.Map. The Editor's BlockRegistry
+ * generates them.
+ *
+ * Wraps the seed in `Y.Doc.transact` with `origin = "seed"` so a
+ * UndoManager scoped to the local origin won't push the seed onto its
+ * stack.
+ */
+export declare function seedYDoc(ydoc: Y.Doc, doc: SobreeDocument, ids: readonly string[]): void;
+/**
+ * Build a *skeleton* block Y.Map — id + kind discriminator + empty
+ * containers, no content. Content lands in `populateBlockContent`
+ * after the map is integrated. Used internally by `seedYDoc` and by
+ * `applyDocumentToYDoc` (`buildBlockYMap` is a one-shot wrapper that
+ * does both phases on an orphan map; only safe for callers that will
+ * insert it inside a transact within the same call stack).
+ */
+export declare function buildSkeletonBlockYMap(id: string, block: Block): Y.Map<unknown>;
+/** Populate the content of an *integrated* block Y.Map. */
+export declare function populateBlockContent(map: Y.Map<unknown>, block: Block): void;
+/**
+ * Populate paragraph content. Caller guarantees the map is integrated
+ * (so its child Y.Text is too).
+ */
+export declare function populateParagraphContent(map: Y.Map<unknown>, block: Paragraph): void;
+/**
+ * One-shot block Y.Map builder — skeleton + content in a single call.
+ * Only safe inside a `Y.Doc.transact` block where the returned map
+ * will be inserted into an integrated parent before any read of its
+ * Y.Text. Otherwise prefer the two-phase builders above.
+ *
+ * Kept for backwards compat with callers that don't yet use the
+ * two-phase pattern.
+ */
+export declare function buildBlockYMap(id: string, block: Block): Y.Map<unknown>;
+/**
+ * @deprecated Use `populateParagraphContent` (renamed for clarity).
+ * Kept as a re-export so callers don't break during migration.
+ */
+export declare const populateParagraphYMap: typeof populateParagraphContent;

package/dist/ydoc/textDiff.d.ts

@@ -0,0 +1,59 @@
+import { DeltaOp } from './runs';
+/**
+ * Compute the minimal Y.Text mutations to bring a Y.Text in sync with
+ * a target delta.
+ *
+ * # Why minimal mutations matter
+ *
+ * Y.Text is a CRDT — every `insert` / `delete` / `format` becomes a
+ * Yjs operation broadcast to peers. The smaller and more targeted the
+ * operations, the less chance of conflicting with concurrent edits.
+ *
+ * Replacing the whole text on every change destroys CRDT semantics:
+ * one peer's "delete-all-and-reinsert" wipes whatever the other peer
+ * was simultaneously typing. The diff in this module is the
+ * difference between "two peers can type in the same paragraph" and
+ * "one peer always wins".
+ *
+ * # Algorithm
+ *
+ * Three paths in increasing generality:
+ *
+ *   1. **No-op** — current and target deltas are structurally identical.
+ *      Skip entirely. Catches the (common) case where a higher-level
+ *      mutation didn't actually change this paragraph.
+ *
+ *   2. **Format-only** — same length and same per-position content
+ *      (chars or embeds), but at least one position has different
+ *      attributes. Walk and call `format()` for each changed range.
+ *      This is the case for "bold the selection" — the text content
+ *      is unchanged, just the marks; using format() instead of
+ *      delete+reinsert preserves CRDT for any concurrent typing
+ *      inside the formatted range.
+ *
+ *   3. **Prefix/suffix replace** — find the longest common prefix and
+ *      longest common suffix of cells, then `delete()` the differing
+ *      middle of the old and `insert()` the differing middle of the
+ *      new. This handles typing (insert at position N), deletion,
+ *      paste, and any other content-changing edit. Concurrent edits
+ *      OUTSIDE the changed range are preserved by Y.Text's CRDT.
+ *
+ * # Cells
+ *
+ * Both deltas are flattened to a `Cell[]` representation: one cell
+ * per character (for string inserts) or per embed (for object inserts).
+ * Cells carry the per-position attributes — Y.Text marks that
+ * surround the chunk get duplicated onto each cell.
+ *
+ * This is allocation-heavy for long paragraphs but bounded by
+ * paragraph length (rarely > 1000 chars). For Phase 1c we can switch
+ * to a streaming diff.
+ */
+import type * as Y from "yjs";
+/**
+ * Apply the difference between Y.Text's current state and `targetDelta`
+ * as the minimal set of Y.Text mutations. Caller is responsible for
+ * wrapping in `Y.Doc.transact` if it wants the changes batched into
+ * one transaction with whatever else.
+ */
+export declare function diffApplyText(yText: Y.Text, targetDelta: readonly DeltaOp[]): void;

package/dist/zoneEdit/index.d.ts

@@ -0,0 +1,22 @@
+import { PageSetup } from '../paperStack/pageSetup';
+export type ZoneKind = "header" | "footer";
+export interface EnterZoneEditOptions {
+    zone: HTMLElement;
+    kind: ZoneKind;
+    stackRoot: HTMLElement;
+    getSetup: () => PageSetup;
+    setSetup: (next: PageSetup) => void;
+    onExit: () => void;
+}
+/**
+ * Make a header or footer zone editable in place. The displayed (substituted)
+ * text is swapped for its template (e.g. "Page {page} of {pages}") so the user
+ * edits the template, not its rendered result. On commit (blur, Enter,
+ * Escape, click outside, or the caller invoking the returned `finish()`)
+ * the new template is written back to the right slot on the PageSetup.
+ *
+ * The returned function exits zone-edit programmatically — block tools call
+ * it when the user clicks the gutter indicator a second time, so the
+ * indicator works as a single toggle for entering and leaving the zone.
+ */
+export declare function enterZoneEdit(opts: EnterZoneEditOptions): () => void;

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@sobree/core",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Embeddable, print-view-first WYSIWYG editor for .docx — framework-free core, plugin architecture, native OOXML round-trip.",
+  "keywords": [
+    "wysiwyg",
+    "editor",
+    "rich-text",
+    "docx",
+    "ooxml",
+    "framework-free",
+    "embeddable",
+    "contenteditable",
+    "pagination",
+    "sobree"
+  ],
+  "license": "MIT",
+  "author": "sobree.dev",
+  "homepage": "https://docs.sobree.dev",
+  "bugs": {
+    "url": "https://github.com/khayll/sobree/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/khayll/sobree.git",
+    "directory": "packages/core"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./tokens.css": {
+      "development": "./src/styles/tokens.css",
+      "default": "./dist/tokens.css"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "fflate": "^0.8.2",
+    "yjs": "^13.6.30"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "build": "vite build && cp src/styles/tokens.css dist/tokens.css",
+    "clean": "rm -rf dist"
+  }
+}