@lensmap/document 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lensmap contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,32 @@
-# Temporary Holding Version
+# @lensmap/document
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Experimental, host-independent Lensmap document engine. Provides YAML analysis,
+semantic graphs, revision-bound source bindings, session identities and bounded
+source-preserving content edits. Does not own layout, browser rendering or LSP.
+
+Requires Node 24.16 or newer. ESM only. The API and `version: v1` authoring format
+are incomplete and experimental; `0.1.x` is not a promise of a stable schema.
+
+```sh
+npm install @lensmap/document@next
+```
+
+```js
+import { DocumentSession } from "@lensmap/document";
+
+const session = new DocumentSession(
+  "file:///notes.lensmap",
+  "version: v1\nnodes: [First thought]\n",
+  1,
+);
+console.log(session.snapshot());
+```
+
+The root export includes `DocumentSchema`, `generateJSONSchema` and the session
+API. `@lensmap/document/v1` exposes the experimental structural schema. Both
+exports include TypeScript declarations. Thought/edge keys are attachment-local
+internal identities, not authored persistent IDs. Source/LSP positions use
+zero-based UTF-16 units.
+
+See the [source and format documentation](https://github.com/nicodoggie/lensmap)
+for supported syntax and limitations. MIT licensed; see `LICENSE`.

package/dist/export-schema.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/export-schema.js

@@ -0,0 +1,9 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { generateJSONSchema } from "./index.js";
+const target = process.argv[2];
+if (!target)
+    throw new Error("Supply the generated schema's output filename.");
+const path = resolve(target);
+await mkdir(dirname(path), { recursive: true });
+await writeFile(path, `${JSON.stringify({ ...generateJSONSchema(), title: "Lensmap experimental v1", $comment: "Generated from the owning Zod input schema. Not a public compatibility promise; document-wide IDs/references are checked by the engine." }, null, 2)}\n`);

package/dist/index.d.ts

@@ -0,0 +1,119 @@
+import { z } from "zod";
+import { type ConnectionType } from "./v1/schema.js";
+export type { ConnectionType, LensmapDocument, Reference, RichNode, } from "./v1/schema.js";
+export { ConnectionTypeSchema, DocumentSchema } from "./v1/schema.js";
+export declare function generateJSONSchema(): z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
+    version: z.ZodLiteral<"v1">;
+    nodes: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodType<import("./v1/schema.js").RichNode, unknown, z.core.$ZodTypeInternals<import("./v1/schema.js").RichNode, unknown>>]>>;
+}, z.core.$strict>>;
+/** Read the edge from the inspected endpoint, independently of structural kind. */
+export declare function connectionWording(type: ConnectionType | undefined, direction: "outgoing" | "incoming"): string;
+type AnchorThought = {
+    readonly key: string;
+    readonly id?: string;
+};
+/** Generated spelling is private to this rendered document version. */
+export declare function thoughtAnchors(nodes: readonly AnchorThought[]): Map<string, string>;
+/** The host decodes the fragment once before calling; authored names stay exact. */
+export declare function resolveThoughtAnchor(nodes: readonly AnchorThought[], decodedAnchor: string): string | undefined;
+export type SourcePosition = {
+    line: number;
+    character: number;
+};
+export type SourceRange = {
+    start: SourcePosition;
+    end: SourcePosition;
+};
+export type SourceSpan = {
+    start: number;
+    end: number;
+};
+export type Thought = {
+    key: string;
+    id?: string;
+    title: string;
+    markdown: string;
+    unresolved: boolean;
+    position?: {
+        x: number;
+        y: number;
+    };
+    path: string;
+    destination?: {
+        kind: "map_link" | "external_link";
+        url: string;
+    };
+};
+export type Connection = {
+    key: string;
+    from: string;
+    to: string;
+    kind: "branch" | "cross";
+    type?: ConnectionType;
+    path: string;
+};
+export type SemanticGraph = {
+    nodes: Thought[];
+    edges: Connection[];
+};
+export type Binding = {
+    key: string;
+    kind: "definition" | "reference";
+    span: SourceSpan;
+    ownerKey?: string;
+};
+export type Diagnostic = {
+    message: string;
+    range: SourceRange;
+};
+export type DocumentSnapshot = {
+    attachmentId?: string;
+    uri: string;
+    revision: number;
+    analyzedRevision: number | null;
+    graphRevision: number | null;
+    valid: boolean;
+    pending: boolean;
+    graph: SemanticGraph | null;
+    diagnostics: Diagnostic[];
+    bindings: Binding[];
+};
+export type ContentPatch = {
+    summary?: string | null;
+    full_text?: string | null;
+};
+export type PreparedEdit = {
+    edits: {
+        range: SourceRange;
+        newText: string;
+    }[];
+    source: string;
+};
+export declare class ContentEditError extends Error {
+    readonly code: "stale-analysis" | "unknown-key" | "unsupported" | "invalid-edit";
+    constructor(code: "stale-analysis" | "unknown-key" | "unsupported" | "invalid-edit", message: string);
+}
+export declare function positionToOffset(source: string, position: SourcePosition): number;
+export declare function offsetToPosition(source: string, offset: number): SourcePosition;
+export declare class DocumentSession {
+    readonly uri: string;
+    private readonly attachmentId;
+    private text;
+    private version;
+    private state;
+    private records;
+    private validSource;
+    private serial;
+    constructor(uri: string, source?: string, revision?: number);
+    get source(): string;
+    get revision(): number;
+    receive(source: string, revision: number): DocumentSnapshot;
+    update(source: string, revision: number): DocumentSnapshot;
+    snapshot(): DocumentSnapshot;
+    private range;
+    analyze(): DocumentSnapshot;
+    locate(position: SourcePosition): string | undefined;
+    definition(key: string): SourceRange | undefined;
+    highlights(position: SourcePosition): SourceRange[];
+    prepareContentEdit(key: string, patch: ContentPatch): PreparedEdit;
+}

package/dist/index.js

@@ -0,0 +1,501 @@
+import { isAlias, isMap, isScalar, parseDocument } from "yaml";
+import { z } from "zod";
+import { DocumentSchema, } from "./v1/schema.js";
+export { ConnectionTypeSchema, DocumentSchema } from "./v1/schema.js";
+export function generateJSONSchema() {
+    return z.toJSONSchema(DocumentSchema, { io: "input" });
+}
+/** Read the edge from the inspected endpoint, independently of structural kind. */
+export function connectionWording(type, direction) {
+    switch (type) {
+        case "precedes":
+            return direction === "outgoing" ? "precedes" : "follows";
+        case "follows":
+            return direction === "outgoing" ? "follows" : "precedes";
+        case "prevents":
+            return direction === "outgoing" ? "prevents" : "is prevented by";
+        case "optional":
+            return "optionally connected to";
+        case "map_link":
+            return direction === "outgoing" ? "links to map" : "map linked from";
+        case "external_link":
+            return direction === "outgoing"
+                ? "links to resource"
+                : "resource linked from";
+        default:
+            return "connected to";
+    }
+}
+/** Generated spelling is private to this rendered document version. */
+export function thoughtAnchors(nodes) {
+    const reserved = new Set(nodes.flatMap((node) => (node.id === undefined ? [] : [node.id])));
+    const anchors = new Map();
+    for (const node of nodes) {
+        if (node.id !== undefined) {
+            anchors.set(node.key, node.id);
+            continue;
+        }
+        const base = `thought-${node.key}`;
+        let anchor = base;
+        let suffix = 0;
+        while (reserved.has(anchor))
+            anchor = `${base}-${++suffix}`;
+        reserved.add(anchor);
+        anchors.set(node.key, anchor);
+    }
+    return anchors;
+}
+/** The host decodes the fragment once before calling; authored names stay exact. */
+export function resolveThoughtAnchor(nodes, decodedAnchor) {
+    for (const [key, anchor] of thoughtAnchors(nodes))
+        if (anchor === decodedAnchor)
+            return key;
+    return undefined;
+}
+let attachmentSerial = 0;
+export class ContentEditError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "ContentEditError";
+    }
+}
+export function positionToOffset(source, position) {
+    let start = 0;
+    for (let line = 0; line < Math.max(0, position.line); line++) {
+        const end = source.indexOf("\n", start);
+        if (end < 0)
+            return source.length;
+        start = end + 1;
+    }
+    const newline = source.indexOf("\n", start);
+    let end = newline < 0 ? source.length : newline;
+    if (end > start && source[end - 1] === "\r")
+        end--;
+    return Math.min(end, start + Math.max(0, position.character));
+}
+export function offsetToPosition(source, offset) {
+    offset = Math.max(0, Math.min(source.length, offset));
+    const before = source.slice(0, offset);
+    const line = before.split("\n").length - 1;
+    return { line, character: offset - (before.lastIndexOf("\n") + 1) };
+}
+function rejectCycles(value, ancestors = new Set()) {
+    if (!value || typeof value !== "object")
+        return;
+    if (ancestors.has(value))
+        throw new Error("YAML alias cycles are not supported; use node_id for graph cycles.");
+    ancestors.add(value);
+    for (const child of Object.values(value))
+        rejectCycles(child, ancestors);
+    ancestors.delete(value);
+}
+export class DocumentSession {
+    uri;
+    attachmentId = `attachment:${++attachmentSerial}`;
+    text;
+    version;
+    state;
+    records = [];
+    validSource = "";
+    serial = 0;
+    constructor(uri, source = "", revision = 0) {
+        this.uri = uri;
+        this.text = source;
+        this.version = revision;
+        this.state = {
+            uri,
+            attachmentId: this.attachmentId,
+            revision,
+            analyzedRevision: null,
+            graphRevision: null,
+            valid: false,
+            pending: true,
+            graph: null,
+            diagnostics: [],
+            bindings: [],
+        };
+        this.analyze();
+    }
+    get source() {
+        return this.text;
+    }
+    get revision() {
+        return this.version;
+    }
+    receive(source, revision) {
+        this.text = source;
+        this.version = revision;
+        this.state = {
+            ...this.state,
+            revision,
+            valid: false,
+            pending: true,
+            bindings: [],
+            diagnostics: [],
+        };
+        return this.snapshot();
+    }
+    update(source, revision) {
+        this.receive(source, revision);
+        return this.analyze();
+    }
+    snapshot() {
+        return structuredClone(this.state);
+    }
+    range(span) {
+        return {
+            start: offsetToPosition(this.text, span.start),
+            end: offsetToPosition(this.text, span.end),
+        };
+    }
+    analyze() {
+        try {
+            const doc = parseDocument(this.text, { uniqueKeys: true });
+            const problem = [...doc.errors, ...doc.warnings][0];
+            if (problem)
+                throw Object.assign(new Error(`YAML: ${problem.message}`), {
+                    offset: problem.pos[0],
+                });
+            const input = doc.toJS();
+            rejectCycles(input);
+            const result = DocumentSchema.safeParse(input);
+            if (!result.success) {
+                // Union alternatives report their paths at the union boundary. Locate
+                // a concrete failing field in the source, not an unrelated line zero.
+                const leaves = (issues, prefix = []) => issues.flatMap((issue) => {
+                    const path = [...prefix, ...issue.path];
+                    return issue.code === "invalid_union"
+                        ? leaves(issue.errors.flat(), path)
+                        : [{ ...issue, path }];
+                });
+                const located = leaves(result.error.issues)
+                    .map((issue) => {
+                    const path = issue.path.filter((part) => typeof part !== "symbol");
+                    if (issue.code === "unrecognized_keys" && issue.keys[0])
+                        path.push(issue.keys[0]);
+                    const ast = doc.getIn(path, true);
+                    return { issue, path, offset: ast?.range?.[0] };
+                })
+                    .filter((item) => item.offset !== undefined)
+                    .sort((a, b) => b.path.length - a.path.length)[0];
+                throw Object.assign(new Error(located?.issue.message ?? z.prettifyError(result.error)), { offset: located?.offset ?? 0 });
+            }
+            const records = [];
+            const edges = [];
+            const bindings = [];
+            const refs = [];
+            const ids = new Map();
+            let prefix = 0;
+            while (prefix < this.validSource.length &&
+                prefix < this.text.length &&
+                this.validSource[prefix] === this.text[prefix])
+                prefix++;
+            let suffix = 0;
+            while (suffix < this.validSource.length - prefix &&
+                suffix < this.text.length - prefix &&
+                this.validSource.at(-suffix - 1) === this.text.at(-suffix - 1))
+                suffix++;
+            const mapped = (n) => n <= prefix
+                ? n
+                : n >= this.validSource.length - suffix
+                    ? n + this.text.length - this.validSource.length
+                    : -1;
+            const visit = (entry, path, parent) => {
+                const pathName = path.join(".");
+                let ast = doc.getIn(path, true);
+                if (!ast) {
+                    for (let length = path.length - 1; length > 0; length--) {
+                        const ancestor = doc.getIn(path.slice(0, length), true);
+                        if (isAlias(ancestor)) {
+                            ast = ancestor;
+                            break;
+                        }
+                    }
+                }
+                // Descendants materialized from aliases point to that alias occurrence;
+                // edits through aliases are explicitly unsupported.
+                // Aliases are distinct occurrences with their own source span.
+                const span = { start: ast?.range?.[0] ?? 0, end: ast?.range?.[1] ?? 0 };
+                if (typeof entry === "object" &&
+                    entry !== null &&
+                    !Array.isArray(entry) &&
+                    "node_id" in entry) {
+                    if (parent)
+                        refs.push({
+                            from: parent,
+                            id: entry.node_id,
+                            type: entry.type,
+                            path: pathName,
+                            span,
+                        });
+                    return;
+                }
+                const content = typeof entry === "string"
+                    ? { full_text: entry }
+                    : Array.isArray(entry)
+                        ? { full_text: null, connections: entry }
+                        : entry;
+                const destination = (content.type === "map_link" || content.type === "external_link") &&
+                    content.url !== undefined
+                    ? { kind: content.type, url: content.url }
+                    : undefined;
+                const fallback = content.summary === undefined && content.full_text === undefined
+                    ? (destination?.url ?? "")
+                    : "";
+                const markdown = content.full_text ?? content.summary ?? fallback;
+                const title = content.summary !== undefined
+                    ? (content.summary ?? "")
+                    : (content.full_text ?? fallback).split(/\r?\n/, 1)[0];
+                const key = `thought:${++this.serial}`;
+                const thought = {
+                    key,
+                    id: content.id,
+                    title,
+                    markdown,
+                    unresolved: title.trim() === "",
+                    position: content.position,
+                    path: pathName,
+                    ...(destination ? { destination } : {}),
+                };
+                records.push({ thought, span, ast });
+                bindings.push({ key, kind: "definition", span });
+                if (content.id !== undefined) {
+                    if (ids.has(content.id))
+                        throw new Error(`${pathName}.id: duplicate id "${content.id}".`);
+                    ids.set(content.id, key);
+                }
+                if (parent)
+                    edges.push({
+                        key: `edge:${key}`,
+                        from: parent,
+                        to: key,
+                        kind: "branch",
+                        ...(content.type !== undefined ? { type: content.type } : {}),
+                        path: pathName,
+                    });
+                content.connections?.forEach((child, i) => {
+                    visit(child, Array.isArray(entry) ? [...path, i] : [...path, "connections", i], key);
+                });
+            };
+            result.data.nodes.forEach((entry, i) => {
+                visit(entry, ["nodes", i]);
+            });
+            // Reconcile the complete parse so newly inserted copies cannot steal
+            // identities from occurrences whose ranges still map to surviving text.
+            const remap = new Map();
+            const remaining = new Set(records);
+            const oldRemaining = new Set(this.records);
+            const assign = (old, current) => {
+                remap.set(current.thought.key, old.thought.key);
+                remaining.delete(current);
+                oldRemaining.delete(old);
+            };
+            for (const old of this.records) {
+                const candidates = [...remaining].filter((r) => isMap(old.ast) === isMap(r.ast) &&
+                    isScalar(old.ast) === isScalar(r.ast) &&
+                    mapped(old.span.end) === r.span.end);
+                if (candidates.length === 1)
+                    assign(old, candidates[0]);
+            }
+            for (const old of [...oldRemaining]) {
+                const candidates = [...remaining].filter((r) => old.thought.id !== undefined
+                    ? r.thought.id === old.thought.id
+                    : r.thought.title === old.thought.title &&
+                        r.thought.markdown === old.thought.markdown);
+                const competing = [...oldRemaining].filter((r) => old.thought.id !== undefined
+                    ? r.thought.id === old.thought.id
+                    : r.thought.title === old.thought.title &&
+                        r.thought.markdown === old.thought.markdown);
+                if (candidates.length === 1 && competing.length === 1)
+                    assign(old, candidates[0]);
+            }
+            for (const old of [...oldRemaining]) {
+                const candidates = [...remaining].filter((r) => isMap(old.ast) === isMap(r.ast) &&
+                    isScalar(old.ast) === isScalar(r.ast) &&
+                    mapped(old.span.start) === r.span.start);
+                if (candidates.length === 1)
+                    assign(old, candidates[0]);
+            }
+            const stable = (key) => remap.get(key) ?? key;
+            for (const record of records)
+                record.thought.key = stable(record.thought.key);
+            for (const binding of bindings)
+                binding.key = stable(binding.key);
+            for (const edge of edges) {
+                edge.from = stable(edge.from);
+                edge.to = stable(edge.to);
+                edge.key = `edge:${edge.to}`;
+            }
+            for (const [id, key] of ids)
+                ids.set(id, stable(key));
+            for (const ref of refs)
+                ref.from = stable(ref.from);
+            const parallelReferences = new Map();
+            for (const ref of refs) {
+                const to = ids.get(ref.id);
+                if (!to)
+                    throw Object.assign(new Error(`${ref.path}.node_id: no node has id "${ref.id}".`), { offset: ref.span.start });
+                if ((ref.type === "map_link" || ref.type === "external_link") &&
+                    records.find((r) => r.thought.key === to)?.thought.destination
+                        ?.kind !== ref.type)
+                    throw Object.assign(new Error(`${ref.path}.type: reference requires a ${ref.type} destination.`), { offset: ref.span.start });
+                const endpoints = `${ref.from}:${to}`;
+                const occurrence = parallelReferences.get(endpoints) ?? 0;
+                parallelReferences.set(endpoints, occurrence + 1);
+                edges.push({
+                    key: `cross:${endpoints}:${occurrence}`,
+                    from: ref.from,
+                    to,
+                    kind: "cross",
+                    ...(ref.type !== undefined ? { type: ref.type } : {}),
+                    path: ref.path,
+                });
+                bindings.push({
+                    key: to,
+                    kind: "reference",
+                    span: ref.span,
+                    ownerKey: ref.from,
+                });
+            }
+            this.records = records;
+            this.validSource = this.text;
+            this.state = {
+                uri: this.uri,
+                attachmentId: this.attachmentId,
+                revision: this.version,
+                analyzedRevision: this.version,
+                graphRevision: this.version,
+                valid: true,
+                pending: false,
+                graph: { nodes: records.map((r) => r.thought), edges },
+                diagnostics: [],
+                bindings,
+            };
+        }
+        catch (error) {
+            const offset = typeof error === "object" && error !== null && "offset" in error
+                ? Number(error.offset)
+                : 0;
+            this.state = {
+                ...this.state,
+                analyzedRevision: this.version,
+                valid: false,
+                pending: false,
+                bindings: [],
+                diagnostics: [
+                    {
+                        message: error instanceof Error ? error.message : String(error),
+                        range: this.range({ start: offset, end: offset }),
+                    },
+                ],
+            };
+        }
+        return this.snapshot();
+    }
+    locate(position) {
+        if (!this.state.valid || this.state.pending)
+            return;
+        const offset = positionToOffset(this.text, position);
+        return this.state.bindings
+            .filter((b) => b.span.start <= offset && offset < b.span.end)
+            .sort((a, b) => a.span.end - a.span.start - (b.span.end - b.span.start))[0]?.key;
+    }
+    definition(key) {
+        if (!this.state.valid || this.state.pending)
+            return;
+        const b = this.state.bindings.find((b) => b.key === key && b.kind === "definition");
+        return b ? this.range(b.span) : undefined;
+    }
+    highlights(position) {
+        const key = this.locate(position);
+        return key
+            ? this.state.bindings
+                .filter((b) => b.key === key)
+                .map((b) => this.range(b.span))
+            : [];
+    }
+    prepareContentEdit(key, patch) {
+        if (!this.state.valid || this.state.pending)
+            throw new ContentEditError("stale-analysis", "Current valid analysis is required.");
+        const record = this.records.find((r) => r.thought.key === key);
+        if (!record)
+            throw new ContentEditError("unknown-key", "Unknown thought key.");
+        const ast = record.ast;
+        const changes = [];
+        const unsupported = () => new ContentEditError("unsupported", "This source form cannot be edited safely.");
+        if (isAlias(ast))
+            throw unsupported();
+        const scalarText = (start, end, value) => {
+            const original = this.text.slice(start, end);
+            const comment = /^[|>][0-9+-]*[ \t]*(#[^\r\n]*)/.exec(original)?.[1];
+            return (value +
+                (comment ? ` ${comment}` : "") +
+                (original.endsWith("\r\n")
+                    ? "\r\n"
+                    : original.endsWith("\n")
+                        ? "\n"
+                        : ""));
+        };
+        const fields = ["summary", "full_text"].filter((field) => patch[field] !== undefined);
+        if (isScalar(ast)) {
+            if (fields.includes("summary"))
+                throw unsupported();
+            if (fields.includes("full_text")) {
+                if (patch.full_text === null)
+                    throw unsupported();
+                changes.push({
+                    ...record.span,
+                    newText: scalarText(record.span.start, record.span.end, JSON.stringify(patch.full_text)),
+                });
+            }
+        }
+        else if (isMap(ast)) {
+            for (const field of fields) {
+                const value = ast.get(field, true);
+                const newText = JSON.stringify(patch[field]);
+                if (value && isScalar(value) && value.range) {
+                    changes.push({
+                        start: value.range[0],
+                        end: value.range[1],
+                        newText: scalarText(value.range[0], value.range[1], newText),
+                    });
+                }
+                else if (value !== undefined)
+                    throw unsupported();
+                else {
+                    if (ast.flow)
+                        throw unsupported();
+                    const first = ast.items[0]?.key;
+                    if (!isScalar(first) || !first.range)
+                        throw unsupported();
+                    const start = first.range[0];
+                    const lineStart = this.text.lastIndexOf("\n", start - 1) + 1;
+                    // Insert before the first key, retaining the existing sequence marker.
+                    const indent = " ".repeat(start - lineStart);
+                    changes.push({
+                        start,
+                        end: start,
+                        newText: `${field}: ${newText}\n${indent}`,
+                    });
+                }
+            }
+        }
+        else if (fields.length)
+            throw unsupported();
+        let source = this.text;
+        for (const change of [...changes].sort((a, b) => b.start - a.start))
+            source =
+                source.slice(0, change.start) +
+                    change.newText +
+                    source.slice(change.end);
+        const candidate = new DocumentSession(this.uri, source, this.version);
+        if (!candidate.snapshot().valid)
+            throw new ContentEditError("invalid-edit", "Proposed content does not form a valid document.");
+        return {
+            source,
+            edits: changes.map((c) => ({ range: this.range(c), newText: c.newText })),
+        };
+    }
+}

package/dist/v1/schema.d.ts

@@ -0,0 +1,53 @@
+import { z } from "zod";
+/** Experimental v1 subset. Fields may be added or refined before v1 stabilizes. */
+export declare const PositionSchema: z.ZodObject<{
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+}, z.core.$strict>;
+export declare const ConnectionTypeSchema: z.ZodEnum<{
+    connected: "connected";
+    external_link: "external_link";
+    follows: "follows";
+    map_link: "map_link";
+    optional: "optional";
+    precedes: "precedes";
+    prevents: "prevents";
+}>;
+export type ConnectionType = z.infer<typeof ConnectionTypeSchema>;
+export declare const ReferenceSchema: z.ZodObject<{
+    node_id: z.ZodString;
+    type: z.ZodOptional<z.ZodEnum<{
+        connected: "connected";
+        external_link: "external_link";
+        follows: "follows";
+        map_link: "map_link";
+        optional: "optional";
+        precedes: "precedes";
+        prevents: "prevents";
+    }>>;
+}, z.core.$strict>;
+declare const NodeContentSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    summary: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    full_text: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    position: z.ZodOptional<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type Reference = z.infer<typeof ReferenceSchema>;
+export type RichNode = z.infer<typeof NodeContentSchema> & {
+    connections?: Connection[];
+    type?: ConnectionType;
+    url?: string;
+};
+export type Connection = string | RichNode | Reference | Connection[];
+export declare const RichNodeSchema: z.ZodType<RichNode>;
+export declare const ConnectionSchema: z.ZodType<Connection>;
+export declare const NodeSchema: z.ZodUnion<readonly [z.ZodString, z.ZodType<RichNode, unknown, z.core.$ZodTypeInternals<RichNode, unknown>>]>;
+export declare const DocumentSchema: z.ZodObject<{
+    version: z.ZodLiteral<"v1">;
+    nodes: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodType<RichNode, unknown, z.core.$ZodTypeInternals<RichNode, unknown>>]>>;
+}, z.core.$strict>;
+export type LensmapDocument = z.infer<typeof DocumentSchema>;
+export {};

package/dist/v1/schema.js

@@ -0,0 +1,66 @@
+import { z } from "zod";
+/** Experimental v1 subset. Fields may be added or refined before v1 stabilizes. */
+export const PositionSchema = z.strictObject({
+    x: z.number().finite(),
+    y: z.number().finite(),
+});
+const IdSchema = z.string().regex(/\S/, "An ID must not be empty.");
+export const ConnectionTypeSchema = z.enum([
+    "connected",
+    "precedes",
+    "follows",
+    "prevents",
+    "optional",
+    "external_link",
+    "map_link",
+]);
+const LocalTypeSchema = z.enum([
+    "connected",
+    "precedes",
+    "follows",
+    "prevents",
+    "optional",
+]);
+export const ReferenceSchema = z.strictObject({
+    node_id: IdSchema,
+    type: ConnectionTypeSchema.optional(),
+});
+const NodeContentSchema = z.strictObject({
+    id: IdSchema.optional(),
+    summary: z.string().nullable().optional(),
+    full_text: z.string().nullable().optional(),
+    position: PositionSchema.optional(),
+});
+const ordinary = (typed) => {
+    const base = typed
+        ? NodeContentSchema.extend({ type: LocalTypeSchema.optional() })
+        : NodeContentSchema;
+    return z.union([
+        base.extend({
+            summary: z.string().nullable(),
+            connections: z.array(ConnectionSchema).optional(),
+        }),
+        base.extend({
+            full_text: z.string().nullable(),
+            connections: z.array(ConnectionSchema).optional(),
+        }),
+    ]);
+};
+const portal = () => NodeContentSchema.extend({
+    type: z.enum(["map_link", "external_link"]),
+    url: z.string().regex(/\S/, "A portal URL must not be blank."),
+    connections: z.array(ConnectionSchema).optional(),
+});
+export const RichNodeSchema = z.lazy(() => z.union([ordinary(true), portal()]));
+const RootNodeSchema = z.lazy(() => z.union([ordinary(false), portal()]));
+export const ConnectionSchema = z.lazy(() => z.union([
+    z.string(),
+    ReferenceSchema,
+    RichNodeSchema,
+    z.array(ConnectionSchema),
+]));
+export const NodeSchema = z.union([z.string(), RootNodeSchema]);
+export const DocumentSchema = z.strictObject({
+    version: z.literal("v1"),
+    nodes: z.array(NodeSchema),
+});

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@lensmap/document",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "license": "MIT",
+  "description": "Experimental Lensmap document engine: YAML analysis, semantic graphs and revision-bound source edits",
+  "version": "0.1.1",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "next",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nicodoggie/lensmap.git",
+    "directory": "packages/document"
+  },
+  "engines": {
+    "node": ">=24.16.0"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./v1": {
+      "types": "./dist/v1/schema.d.ts",
+      "default": "./dist/v1/schema.js"
+    }
+  },
+  "dependencies": {
+    "yaml": "2.9.1",
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "24.19.2",
+    "ajv": "8.20.0",
+    "typescript": "7.0.2",
+    "vitest": "5.1.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }