@commentray/core 0.0.1 → 0.0.2

package/dist/github-url.js

@@ -0,0 +1,25 @@
+import { normalizeRepoRelativePath } from "./paths.js";
+/**
+ * Parses a GitHub repository web URL into owner + repo name (no API calls).
+ * Accepts optional trailing slash and `.git` suffix.
+ */
+export function parseGithubRepoWebUrl(url) {
+    const t = url.trim().replace(/\/+$/, "");
+    const m = t.match(/^https?:\/\/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?$/i);
+    if (!m)
+        return null;
+    return { owner: m[1], repo: m[2] };
+}
+/**
+ * Builds a `https://github.com/owner/repo/blob/<branch>/path` URL for a repo-relative file path.
+ * Used for static-site “open another file” links when only `_site/index.html` is deployed.
+ */
+export function githubRepoBlobFileUrl(owner, repo, branch, repoRelativePath) {
+    const posix = normalizeRepoRelativePath(repoRelativePath.replace(/\\/g, "/"));
+    const tail = posix
+        .split("/")
+        .map((s) => encodeURIComponent(s))
+        .join("/");
+    return `https://github.com/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/blob/${encodeURIComponent(branch)}/${tail}`;
+}
+//# sourceMappingURL=github-url.js.map

package/dist/github-url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-url.js","sourceRoot":"","sources":["../src/github-url.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAEvD;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAW;IAC/C,MAAM,CAAC,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACzC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAC5E,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACrC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAAa,EACb,IAAY,EACZ,MAAc,EACd,gBAAwB;IAExB,MAAM,KAAK,GAAG,yBAAyB,CAAC,gBAAgB,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC;IAC9E,MAAM,IAAI,GAAG,KAAK;SACf,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC;SACjC,IAAI,CAAC,GAAG,CAAC,CAAC;IACb,OAAO,sBAAsB,kBAAkB,CAAC,KAAK,CAAC,IAAI,kBAAkB,CAAC,IAAI,CAAC,SAAS,kBAAkB,CAAC,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;AAClI,CAAC"}

package/dist/index.d.ts

@@ -1,8 +1,16 @@
-export type { CommentrayBlock, CommentrayIndex, SourceFileIndexEntry } from "./model.js";
+export type { CommentrayBlock, CommentrayBlockFingerprint, CommentrayIndex, SourceFileIndexEntry, } from "./model.js";
 export { CURRENT_SCHEMA_VERSION } from "./model.js";
-export { commentrayMarkdownPath, defaultMetadataIndexPath, normalizeRepoRelativePath, } from "./paths.js";
-export type { CommentrayToml, ResolvedCommentrayConfig, ResolvedStaticSite } from "./config.js";
+export type { AddBlockToIndexInput, BlockRange, CreateBlockForRangeInput, CreatedBlock, } from "./blocks.js";
+export { addBlockToIndex, appendBlockToCommentray, createBlockForRange, generateBlockId, } from "./blocks.js";
+export { assertValidAngleId } from "./angles.js";
+export { ensureAnglesSentinelFile, upsertAngleDefinitionInCommentrayToml } from "./angles-toml.js";
+export type { UpsertAngleDefinitionInput } from "./angles-toml.js";
+export { defaultAngleIdForOpen, FALLBACK_DEFAULT_ANGLE_ID, resolveCommentrayMarkdownPath, } from "./commentray-path-resolution.js";
+export type { ResolvedCommentrayMarkdownPath } from "./commentray-path-resolution.js";
+export { commentrayAnglesLayoutEnabled, commentrayAnglesSentinelPath, commentrayMarkdownPath, commentrayMarkdownPathForAngle, defaultMetadataIndexPath, normalizeRepoRelativePath, } from "./paths.js";
+export type { CommentrayToml, ResolvedAngleDefinition, ResolvedAngles, ResolvedCommentrayConfig, ResolvedGithubNavLink, ResolvedStaticSite, } from "./config.js";
 export { loadCommentrayConfig, mergeCommentrayConfig } from "./config.js";
+export { githubRepoBlobFileUrl, parseGithubRepoWebUrl } from "./github-url.js";
 export { assertValidIndex, emptyIndex } from "./metadata.js";
 export { migrateIndex } from "./migrate.js";
 export type { ParsedAnchor } from "./anchors.js";
@@ -12,6 +20,8 @@ export { GitScmProvider } from "./scm/git-scm-provider.js";
 export type { BlockDiagnostic } from "./staleness.js";
 export { diagnoseBlock } from "./staleness.js";
 export type { ValidationIssue, ValidationResult } from "./validate-project.js";
-export { readIndex, validateProject } from "./validate-project.js";
+export { readIndex, validateProject, writeIndex } from "./validate-project.js";
 export { runCommanderMain } from "./cli-bootstrap.js";
+export type { BlockScrollLink } from "./scroll-sync.js";
+export { buildBlockScrollLinks, pickCommentrayLineForSourceScroll, pickSourceLine0ForCommentrayScroll, } from "./scroll-sync.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACzF,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EACL,sBAAsB,EACtB,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,cAAc,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAChG,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC5D,YAAY,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,eAAe,EACf,0BAA0B,EAC1B,eAAe,EACf,oBAAoB,GACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACpD,YAAY,EACV,oBAAoB,EACpB,UAAU,EACV,wBAAwB,EACxB,YAAY,GACb,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,mBAAmB,EACnB,eAAe,GAChB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,wBAAwB,EAAE,qCAAqC,EAAE,MAAM,kBAAkB,CAAC;AACnG,YAAY,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AACnE,OAAO,EACL,qBAAqB,EACrB,yBAAyB,EACzB,6BAA6B,GAC9B,MAAM,iCAAiC,CAAC;AACzC,YAAY,EAAE,8BAA8B,EAAE,MAAM,iCAAiC,CAAC;AACtF,OAAO,EACL,6BAA6B,EAC7B,4BAA4B,EAC5B,sBAAsB,EACtB,8BAA8B,EAC9B,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,cAAc,EACd,uBAAuB,EACvB,cAAc,EACd,wBAAwB,EACxB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAC/E,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC5D,YAAY,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,YAAY,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EACL,qBAAqB,EACrB,iCAAiC,EACjC,kCAAkC,GACnC,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -1,11 +1,17 @@
 export { CURRENT_SCHEMA_VERSION } from "./model.js";
-export { commentrayMarkdownPath, defaultMetadataIndexPath, normalizeRepoRelativePath, } from "./paths.js";
+export { addBlockToIndex, appendBlockToCommentray, createBlockForRange, generateBlockId, } from "./blocks.js";
+export { assertValidAngleId } from "./angles.js";
+export { ensureAnglesSentinelFile, upsertAngleDefinitionInCommentrayToml } from "./angles-toml.js";
+export { defaultAngleIdForOpen, FALLBACK_DEFAULT_ANGLE_ID, resolveCommentrayMarkdownPath, } from "./commentray-path-resolution.js";
+export { commentrayAnglesLayoutEnabled, commentrayAnglesSentinelPath, commentrayMarkdownPath, commentrayMarkdownPathForAngle, defaultMetadataIndexPath, normalizeRepoRelativePath, } from "./paths.js";
 export { loadCommentrayConfig, mergeCommentrayConfig } from "./config.js";
+export { githubRepoBlobFileUrl, parseGithubRepoWebUrl } from "./github-url.js";
 export { assertValidIndex, emptyIndex } from "./metadata.js";
 export { migrateIndex } from "./migrate.js";
 export { formatLineRange, parseAnchor } from "./anchors.js";
 export { GitScmProvider } from "./scm/git-scm-provider.js";
 export { diagnoseBlock } from "./staleness.js";
-export { readIndex, validateProject } from "./validate-project.js";
+export { readIndex, validateProject, writeIndex } from "./validate-project.js";
 export { runCommanderMain } from "./cli-bootstrap.js";
+export { buildBlockScrollLinks, pickCommentrayLineForSourceScroll, pickSourceLine0ForCommentrayScroll, } from "./scroll-sync.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EACL,sBAAsB,EACtB,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE5D,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAE3D,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAOpD,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,mBAAmB,EACnB,eAAe,GAChB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,wBAAwB,EAAE,qCAAqC,EAAE,MAAM,kBAAkB,CAAC;AAEnG,OAAO,EACL,qBAAqB,EACrB,yBAAyB,EACzB,6BAA6B,GAC9B,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EACL,6BAA6B,EAC7B,4BAA4B,EAC5B,sBAAsB,EACtB,8BAA8B,EAC9B,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,YAAY,CAAC;AASpB,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAC/E,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE5D,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAE3D,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,EACL,qBAAqB,EACrB,iCAAiC,EACjC,kCAAkC,GACnC,MAAM,kBAAkB,CAAC"}

package/dist/metadata.js

@@ -1,55 +1,81 @@
 import { CURRENT_SCHEMA_VERSION } from "./model.js";
 export function emptyIndex() {
-    return { schemaVersion: CURRENT_SCHEMA_VERSION, bySourceFile: {} };
+    return { schemaVersion: CURRENT_SCHEMA_VERSION, byCommentrayPath: {} };
 }
 export function assertValidIndex(value) {
     if (typeof value !== "object" || value === null) {
-        throw new Error("index.json must be a JSON object");
+        throw new TypeError("index.json must be a JSON object");
     }
     const obj = value;
     const schemaVersion = obj.schemaVersion;
     if (schemaVersion !== CURRENT_SCHEMA_VERSION) {
         throw new Error(`Unsupported schemaVersion: ${String(schemaVersion)}`);
     }
-    const bySourceFile = obj.bySourceFile;
-    if (typeof bySourceFile !== "object" || bySourceFile === null) {
-        throw new Error("index.json.bySourceFile must be an object");
+    const byCommentrayPath = obj.byCommentrayPath;
+    if (typeof byCommentrayPath !== "object" || byCommentrayPath === null) {
+        throw new TypeError("index.json.byCommentrayPath must be an object");
     }
-    for (const [key, entry] of Object.entries(bySourceFile)) {
-        validateSourceEntry(key, entry);
+    for (const [key, entry] of Object.entries(byCommentrayPath)) {
+        validateCommentrayEntry(key, entry);
     }
     return obj;
 }
-function validateSourceEntry(sourcePath, entry) {
+function validateCommentrayEntry(commentrayPathKey, entry) {
     if (typeof entry !== "object" || entry === null) {
-        throw new Error(`Invalid index entry for ${sourcePath}`);
+        throw new TypeError(`Invalid index entry for ${commentrayPathKey}`);
     }
     const e = entry;
-    if (typeof e.sourcePath !== "string")
-        throw new Error(`Missing sourcePath for ${sourcePath}`);
+    if (typeof e.sourcePath !== "string") {
+        throw new TypeError(`Missing sourcePath for ${commentrayPathKey}`);
+    }
     if (typeof e.commentrayPath !== "string") {
-        throw new Error(`Missing commentrayPath for ${sourcePath}`);
+        throw new TypeError(`Missing commentrayPath for ${commentrayPathKey}`);
+    }
+    if (e.commentrayPath !== commentrayPathKey) {
+        throw new TypeError(`index key must equal entry.commentrayPath (key=${commentrayPathKey}, entry=${e.commentrayPath})`);
+    }
+    if (!Array.isArray(e.blocks)) {
+        throw new TypeError(`blocks must be an array for ${commentrayPathKey}`);
     }
-    if (!Array.isArray(e.blocks))
-        throw new Error(`blocks must be an array for ${sourcePath}`);
     for (const block of e.blocks)
-        validateBlock(sourcePath, block);
+        validateBlock(commentrayPathKey, block);
 }
-function validateBlock(sourcePath, block) {
+function validateBlock(commentrayPathKey, block) {
     if (typeof block !== "object" || block === null) {
-        throw new Error(`Invalid block under ${sourcePath}`);
+        throw new TypeError(`Invalid block under ${commentrayPathKey}`);
     }
     const b = block;
-    if (typeof b.id !== "string")
-        throw new Error(`block.id must be a string under ${sourcePath}`);
+    if (typeof b.id !== "string") {
+        throw new TypeError(`block.id must be a string under ${commentrayPathKey}`);
+    }
     if (typeof b.anchor !== "string") {
-        throw new Error(`block.anchor must be a string under ${sourcePath}`);
+        throw new TypeError(`block.anchor must be a string under ${commentrayPathKey}`);
     }
     if (b.lastVerifiedCommit !== undefined && typeof b.lastVerifiedCommit !== "string") {
-        throw new Error(`block.lastVerifiedCommit must be a string when present under ${sourcePath}`);
+        throw new TypeError(`block.lastVerifiedCommit must be a string when present under ${commentrayPathKey}`);
     }
     if (b.lastVerifiedBlob !== undefined && typeof b.lastVerifiedBlob !== "string") {
-        throw new Error(`block.lastVerifiedBlob must be a string when present under ${sourcePath}`);
+        throw new TypeError(`block.lastVerifiedBlob must be a string when present under ${commentrayPathKey}`);
+    }
+    if (b.markerId !== undefined && typeof b.markerId !== "string") {
+        throw new TypeError(`block.markerId must be a string when present under ${commentrayPathKey}`);
+    }
+    if (b.fingerprint !== undefined)
+        validateFingerprint(commentrayPathKey, b.fingerprint);
+}
+function validateFingerprint(commentrayPathKey, fp) {
+    if (typeof fp !== "object" || fp === null) {
+        throw new TypeError(`block.fingerprint must be an object under ${commentrayPathKey}`);
+    }
+    const f = fp;
+    if (typeof f.startLine !== "string") {
+        throw new TypeError(`block.fingerprint.startLine must be a string under ${commentrayPathKey}`);
+    }
+    if (typeof f.endLine !== "string") {
+        throw new TypeError(`block.fingerprint.endLine must be a string under ${commentrayPathKey}`);
+    }
+    if (typeof f.lineCount !== "number" || !Number.isInteger(f.lineCount) || f.lineCount < 1) {
+        throw new TypeError(`block.fingerprint.lineCount must be a positive integer under ${commentrayPathKey}`);
     }
 }
 //# sourceMappingURL=metadata.js.map

package/dist/metadata.js.map

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

package/dist/migrate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,eAAe,EAGrB,MAAM,YAAY,CAAC;AAEpB,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG;IAAE,KAAK,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CA2BvF"}
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,eAAe,EAGrB,MAAM,YAAY,CAAC;AAIpB,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG;IAAE,KAAK,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAqCvF"}

package/dist/migrate.js

@@ -1,26 +1,32 @@
 import { CURRENT_SCHEMA_VERSION, } from "./model.js";
+const LEGACY_SCHEMA_VERSION = 2;
 /** Returns migrated index and whether the file should be rewritten. */
 export function migrateIndex(raw) {
     if (typeof raw !== "object" || raw === null) {
         return {
-            index: { schemaVersion: CURRENT_SCHEMA_VERSION, bySourceFile: {} },
+            index: { schemaVersion: CURRENT_SCHEMA_VERSION, byCommentrayPath: {} },
             changed: true,
         };
     }
     const obj = raw;
     const version = obj.schemaVersion;
     if (version === CURRENT_SCHEMA_VERSION) {
-        return { index: obj, changed: false };
+        const index = obj;
+        return { index, changed: false };
     }
-    if (version === undefined || version === 0 || version === 1) {
-        const bySourceFile = normalizeBySourceFile(obj.bySourceFile);
+    if (version === LEGACY_SCHEMA_VERSION ||
+        version === undefined ||
+        version === 0 ||
+        version === 1) {
+        const byCommentrayPath = toByCommentrayPath(obj);
         const next = {
             schemaVersion: CURRENT_SCHEMA_VERSION,
-            bySourceFile,
+            byCommentrayPath,
         };
         const before = JSON.stringify({
             schemaVersion: version ?? 0,
             bySourceFile: obj.bySourceFile ?? {},
+            byCommentrayPath: obj.byCommentrayPath ?? {},
         });
         const after = JSON.stringify(next);
         const changed = before !== after;
@@ -28,12 +34,28 @@ export function migrateIndex(raw) {
     }
     throw new Error(`Cannot migrate from schemaVersion ${String(version)}`);
 }
-function normalizeBySourceFile(by) {
-    if (typeof by !== "object" || by === null)
-        return {};
+function toByCommentrayPath(obj) {
+    if (obj.byCommentrayPath &&
+        typeof obj.byCommentrayPath === "object" &&
+        obj.byCommentrayPath !== null) {
+        const out = {};
+        for (const [k, entry] of Object.entries(obj.byCommentrayPath)) {
+            out[k] = normalizeEntry(entry);
+        }
+        return out;
+    }
+    const bySourceFile = obj.bySourceFile;
     const out = {};
-    for (const [k, entry] of Object.entries(by)) {
-        out[k] = normalizeEntry(entry);
+    if (typeof bySourceFile !== "object" || bySourceFile === null) {
+        return out;
+    }
+    for (const [, entry] of Object.entries(bySourceFile)) {
+        const norm = normalizeEntry(entry);
+        const cp = norm.commentrayPath;
+        if (out[cp]) {
+            throw new Error(`Duplicate commentrayPath in legacy index: ${cp}`);
+        }
+        out[cp] = norm;
     }
     return out;
 }

package/dist/migrate.js.map

@@ -1 +1 @@
-{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAEpB,uEAAuE;AACvE,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QAC5C,OAAO;YACL,KAAK,EAAE,EAAE,aAAa,EAAE,sBAAsB,EAAE,YAAY,EAAE,EAAE,EAAE;YAClE,OAAO,EAAE,IAAI;SACd,CAAC;IACJ,CAAC;IACD,MAAM,GAAG,GAAG,GAA8B,CAAC;IAC3C,MAAM,OAAO,GAAG,GAAG,CAAC,aAAa,CAAC;IAClC,IAAI,OAAO,KAAK,sBAAsB,EAAE,CAAC;QACvC,OAAO,EAAE,KAAK,EAAE,GAAsB,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC3D,CAAC;IACD,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,EAAE,CAAC;QAC5D,MAAM,YAAY,GAAG,qBAAqB,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;QAC7D,MAAM,IAAI,GAAoB;YAC5B,aAAa,EAAE,sBAAsB;YACrC,YAAY;SACb,CAAC;QACF,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC;YAC5B,aAAa,EAAE,OAAO,IAAI,CAAC;YAC3B,YAAY,EAAE,GAAG,CAAC,YAAY,IAAI,EAAE;SACrC,CAAC,CAAC;QACH,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QACnC,MAAM,OAAO,GAAG,MAAM,KAAK,KAAK,CAAC;QACjC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAClC,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,qCAAqC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;AAC1E,CAAC;AAED,SAAS,qBAAqB,CAAC,EAAW;IACxC,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC;IACrD,MAAM,GAAG,GAAyC,EAAE,CAAC;IACrD,KAAK,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,EAA6B,CAAC,EAAE,CAAC;QACvE,GAAG,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,cAAc,CAAC,KAAc;IACpC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;IACzC,CAAC;IACD,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,IAAI,OAAO,CAAC,CAAC,cAAc,KAAK,QAAQ,EAAE,CAAC;QACzC,OAAO,CAAyB,CAAC;IACnC,CAAC;IACD,IAAI,OAAO,CAAC,CAAC,cAAc,KAAK,QAAQ,EAAE,CAAC;QACzC,MAAM,EAAE,cAAc,EAAE,GAAG,IAAI,EAAE,GAAG,CAAC,CAAC;QACtC,OAAO,EAAE,GAAG,IAAI,EAAE,cAAc,EAAE,cAAc,EAA0B,CAAC;IAC7E,CAAC;IACD,OAAO,CAAyB,CAAC;AACnC,CAAC"}
+{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":"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"}

package/dist/model.d.ts

@@ -1,9 +1,40 @@
+/**
+ * Content fingerprint of a source range, used to re-resolve the block's
+ * anchor after lines drift (insertions or deletions in the source).
+ *
+ * A fingerprint is intentionally narrow: trimmed text of the first and last
+ * lines plus the original line count. Re-resolution is a search, not a
+ * guarantee: when the fingerprint still appears uniquely near the old
+ * location we silently update the line numbers; otherwise we surface a
+ * diagnostic so a human can decide.
+ */
+export type CommentrayBlockFingerprint = {
+    /** Trimmed content of the first line of the original range. */
+    startLine: string;
+    /** Trimmed content of the last line of the original range. */
+    endLine: string;
+    /** Number of lines the range originally spanned (end - start + 1). */
+    lineCount: number;
+};
 /** Commentray block aligned to a region of a primary source file. */
 export type CommentrayBlock = {
     /** Stable id within the commentray markdown file. */
     id: string;
     /** Human or machine anchor string (see anchor grammar in docs). */
     anchor: string;
+    /**
+     * Optional drift-resolution fingerprint. Present when the block's range
+     * was captured from source content; absent when the anchor is purely a
+     * symbol or marker reference that does not need content-based re-sync.
+     */
+    fingerprint?: CommentrayBlockFingerprint;
+    /**
+     * Optional marker-based anchor. When set, drift resolution looks for a
+     * pair of host-language comments of the form `commentray:start id=<markerId>`
+     * and `commentray:end` in the source; the lines between them become the
+     * block's effective range. Markers are drift-proof but invasive.
+     */
+    markerId?: string;
     /** Last human-verified commit (full SHA) when this block was considered accurate. */
     lastVerifiedCommit?: string;
     /** Git blob id at verification time for the primary file (when known). */
@@ -21,7 +52,11 @@ export type SourceFileIndexEntry = {
 /** Root metadata document stored as JSON under `.commentray/metadata/`. */
 export type CommentrayIndex = {
     schemaVersion: number;
-    bySourceFile: Record<string, SourceFileIndexEntry>;
+    /**
+     * Blocks grouped by repo-relative commentray Markdown path so multiple **Angles**
+     * for the same `sourcePath` each keep their own block lists (schema v3+).
+     */
+    byCommentrayPath: Record<string, SourceFileIndexEntry>;
 };
-export declare const CURRENT_SCHEMA_VERSION: 2;
+export declare const CURRENT_SCHEMA_VERSION: 3;
 //# sourceMappingURL=model.d.ts.map

package/dist/model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,MAAM,MAAM,eAAe,GAAG;IAC5B,qDAAqD;IACrD,EAAE,EAAE,MAAM,CAAC;IACX,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf,qFAAqF;IACrF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,0EAA0E;IAC1E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B,CAAC;AAEF,2EAA2E;AAC3E,MAAM,MAAM,eAAe,GAAG;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;CACpD,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAG,CAAU,CAAC"}
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,MAAM,0BAA0B,GAAG;IACvC,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,qEAAqE;AACrE,MAAM,MAAM,eAAe,GAAG;IAC5B,qDAAqD;IACrD,EAAE,EAAE,MAAM,CAAC;IACX,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,WAAW,CAAC,EAAE,0BAA0B,CAAC;IACzC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qFAAqF;IACrF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,0EAA0E;IAC1E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B,CAAC;AAEF,2EAA2E;AAC3E,MAAM,MAAM,eAAe,GAAG;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;CACxD,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAG,CAAU,CAAC"}

package/dist/model.js

@@ -1,2 +1,2 @@
-export const CURRENT_SCHEMA_VERSION = 2;
+export const CURRENT_SCHEMA_VERSION = 3;
 //# sourceMappingURL=model.js.map

package/dist/model.js.map

@@ -1 +1 @@
-{"version":3,"file":"model.js","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AA4BA,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAU,CAAC"}
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAgEA,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAU,CAAC"}

package/dist/paths.d.ts

@@ -11,8 +11,24 @@
  * `..` segments are traversal.
  */
 export declare function normalizeRepoRelativePath(relativePath: string): string;
-/** Commentray Markdown path for a repo-relative source file. */
+/** Commentray Markdown path for a repo-relative source file (implicit default angle, flat layout). */
 export declare function commentrayMarkdownPath(sourceRepoRelativePath: string): string;
+/**
+ * Repo-relative path to the **Angles sentinel**: if this path exists as a file or directory under
+ * the storage root, the repository opts into per-source **Angles** layout (see `docs/spec/storage.md`).
+ * When absent, the flat `{storage}/source/{P}.md` layout is the only supported shape.
+ */
+export declare function commentrayAnglesSentinelPath(storageDir?: string): string;
+/**
+ * Returns true when the repository opts into **Angles** layout: `{storage}/source/.default` exists
+ * (file or directory). When false, only the flat `{storage}/source/{P}.md` mapping applies.
+ */
+export declare function commentrayAnglesLayoutEnabled(repoRoot: string, storageDir?: string): boolean;
+/**
+ * Repo-relative path to commentray for `sourceRepoRelativePath` at a named **Angle** (multi-angle layout).
+ * Example: `README.md` + `architecture` → `.commentray/source/README.md/architecture.md` (with default storage dir).
+ */
+export declare function commentrayMarkdownPathForAngle(sourceRepoRelativePath: string, angleId: string, storageDir?: string): string;
 /** Default metadata index location (repo-relative). */
 export declare function defaultMetadataIndexPath(): string;
 //# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAWtE;AAED,gEAAgE;AAChE,wBAAgB,sBAAsB,CAAC,sBAAsB,EAAE,MAAM,GAAG,MAAM,CAG7E;AAED,uDAAuD;AACvD,wBAAgB,wBAAwB,IAAI,MAAM,CAEjD"}
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAWtE;AAED,sGAAsG;AACtG,wBAAgB,sBAAsB,CAAC,sBAAsB,EAAE,MAAM,GAAG,MAAM,CAG7E;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,UAAU,SAAgB,GAAG,MAAM,CAG/E;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,MAAM,EAChB,UAAU,SAAgB,GACzB,OAAO,CAIT;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAC5C,sBAAsB,EAAE,MAAM,EAC9B,OAAO,EAAE,MAAM,EACf,UAAU,SAAgB,GACzB,MAAM,CAKR;AAED,uDAAuD;AACvD,wBAAgB,wBAAwB,IAAI,MAAM,CAEjD"}

package/dist/paths.js

@@ -1,4 +1,6 @@
+import fs from "node:fs";
 import path from "node:path";
+import { assertValidAngleId } from "./angles.js";
 /**
  * Normalize a repo-relative path to POSIX separators and reject anything that
  * would escape the repository root when joined with it.
@@ -23,11 +25,39 @@ export function normalizeRepoRelativePath(relativePath) {
     }
     return segments.join("/");
 }
-/** Commentray Markdown path for a repo-relative source file. */
+/** Commentray Markdown path for a repo-relative source file (implicit default angle, flat layout). */
 export function commentrayMarkdownPath(sourceRepoRelativePath) {
     const normalized = normalizeRepoRelativePath(sourceRepoRelativePath);
     return path.posix.join(".commentray", "source", `${normalized}.md`);
 }
+/**
+ * Repo-relative path to the **Angles sentinel**: if this path exists as a file or directory under
+ * the storage root, the repository opts into per-source **Angles** layout (see `docs/spec/storage.md`).
+ * When absent, the flat `{storage}/source/{P}.md` layout is the only supported shape.
+ */
+export function commentrayAnglesSentinelPath(storageDir = ".commentray") {
+    const root = normalizeRepoRelativePath(storageDir.replaceAll("\\", "/"));
+    return path.posix.join(root, "source", ".default");
+}
+/**
+ * Returns true when the repository opts into **Angles** layout: `{storage}/source/.default` exists
+ * (file or directory). When false, only the flat `{storage}/source/{P}.md` mapping applies.
+ */
+export function commentrayAnglesLayoutEnabled(repoRoot, storageDir = ".commentray") {
+    const sentinel = commentrayAnglesSentinelPath(storageDir);
+    const absolute = path.join(repoRoot, ...sentinel.split("/"));
+    return fs.existsSync(absolute);
+}
+/**
+ * Repo-relative path to commentray for `sourceRepoRelativePath` at a named **Angle** (multi-angle layout).
+ * Example: `README.md` + `architecture` → `.commentray/source/README.md/architecture.md` (with default storage dir).
+ */
+export function commentrayMarkdownPathForAngle(sourceRepoRelativePath, angleId, storageDir = ".commentray") {
+    const normalized = normalizeRepoRelativePath(sourceRepoRelativePath);
+    const sid = assertValidAngleId(angleId);
+    const root = normalizeRepoRelativePath(storageDir.replaceAll("\\", "/"));
+    return path.posix.join(root, "source", normalized, `${sid}.md`);
+}
 /** Default metadata index location (repo-relative). */
 export function defaultMetadataIndexPath() {
     return path.posix.join(".commentray", "metadata", "index.json");

package/dist/paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,yBAAyB,CAAC,YAAoB;IAC5D,MAAM,KAAK,GAAG,YAAY,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACjD,IAAI,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,mDAAmD,YAAY,GAAG,CAAC,CAAC;IACtF,CAAC;IACD,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC3C,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC;IAC1E,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CAAC,iCAAiC,YAAY,EAAE,CAAC,CAAC;IACnE,CAAC;IACD,OAAO,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC5B,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,sBAAsB,CAAC,sBAA8B;IACnE,MAAM,UAAU,GAAG,yBAAyB,CAAC,sBAAsB,CAAC,CAAC;IACrE,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,aAAa,EAAE,QAAQ,EAAE,GAAG,UAAU,KAAK,CAAC,CAAC;AACtE,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,wBAAwB;IACtC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,aAAa,EAAE,UAAU,EAAE,YAAY,CAAC,CAAC;AAClE,CAAC"}
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,yBAAyB,CAAC,YAAoB;IAC5D,MAAM,KAAK,GAAG,YAAY,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACjD,IAAI,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,mDAAmD,YAAY,GAAG,CAAC,CAAC;IACtF,CAAC;IACD,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC3C,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC;IAC1E,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CAAC,iCAAiC,YAAY,EAAE,CAAC,CAAC;IACnE,CAAC;IACD,OAAO,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC5B,CAAC;AAED,sGAAsG;AACtG,MAAM,UAAU,sBAAsB,CAAC,sBAA8B;IACnE,MAAM,UAAU,GAAG,yBAAyB,CAAC,sBAAsB,CAAC,CAAC;IACrE,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,aAAa,EAAE,QAAQ,EAAE,GAAG,UAAU,KAAK,CAAC,CAAC;AACtE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,4BAA4B,CAAC,UAAU,GAAG,aAAa;IACrE,MAAM,IAAI,GAAG,yBAAyB,CAAC,UAAU,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;IACzE,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;AACrD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,6BAA6B,CAC3C,QAAgB,EAChB,UAAU,GAAG,aAAa;IAE1B,MAAM,QAAQ,GAAG,4BAA4B,CAAC,UAAU,CAAC,CAAC;IAC1D,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7D,OAAO,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;AACjC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,8BAA8B,CAC5C,sBAA8B,EAC9B,OAAe,EACf,UAAU,GAAG,aAAa;IAE1B,MAAM,UAAU,GAAG,yBAAyB,CAAC,sBAAsB,CAAC,CAAC;IACrE,MAAM,GAAG,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IACxC,MAAM,IAAI,GAAG,yBAAyB,CAAC,UAAU,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;IACzE,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,GAAG,KAAK,CAAC,CAAC;AAClE,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,wBAAwB;IACtC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,aAAa,EAAE,UAAU,EAAE,YAAY,CAAC,CAAC;AAClE,CAAC"}

package/dist/scroll-sync.d.ts

@@ -0,0 +1,27 @@
+import type { CommentrayIndex } from "./model.js";
+/** One block as needed for scroll correlation (0-based commentray line, 1-based source range). */
+export type BlockScrollLink = {
+    commentrayLine: number;
+    sourceStart: number;
+    sourceEnd: number;
+};
+/**
+ * Correlate index blocks (line anchors + ids) with `<!-- commentray:block id=… -->`
+ * markers in commentray. Only `lines:` anchors with a visible
+ * marker participate. Sorted by `sourceStart`.
+ */
+export declare function buildBlockScrollLinks(index: CommentrayIndex | null | undefined, sourceRelative: string, commentrayPath: string, commentrayMarkdown: string): BlockScrollLink[];
+/**
+ * Choose which commentray line (0-based) to reveal so the commentary matches
+ * the top of the source viewport. Prefers the block whose source range
+ * **contains** the top line; otherwise the nearest preceding block; if above
+ * all blocks, the first block.
+ */
+export declare function pickCommentrayLineForSourceScroll(blocks: BlockScrollLink[], topSourceLine1Based: number): number | null;
+/**
+ * Choose a 0-based source line to reveal from the top of the commentray
+ * viewport: the block whose marker is at or above that line wins; reveal the
+ * start of its source range.
+ */
+export declare function pickSourceLine0ForCommentrayScroll(blocks: BlockScrollLink[], topCommentrayLine0Based: number): number | null;
+//# sourceMappingURL=scroll-sync.d.ts.map

package/dist/scroll-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-sync.d.ts","sourceRoot":"","sources":["../src/scroll-sync.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,kGAAkG;AAClG,MAAM,MAAM,eAAe,GAAG;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAcF;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,EACzC,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,MAAM,EACtB,kBAAkB,EAAE,MAAM,GACzB,eAAe,EAAE,CAkBnB;AAED;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAC/C,MAAM,EAAE,eAAe,EAAE,EACzB,mBAAmB,EAAE,MAAM,GAC1B,MAAM,GAAG,IAAI,CAaf;AAED;;;;GAIG;AACH,wBAAgB,kCAAkC,CAChD,MAAM,EAAE,eAAe,EAAE,EACzB,uBAAuB,EAAE,MAAM,GAC9B,MAAM,GAAG,IAAI,CAQf"}

package/dist/scroll-sync.js

@@ -0,0 +1,80 @@
+import { parseAnchor } from "./anchors.js";
+const BLOCK_MARKER_RE = /<!-- commentray:block id=([a-z0-9]+) -->/;
+function markerLineByIdFromMarkdown(markdown) {
+    const map = new Map();
+    const lines = markdown.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        const match = BLOCK_MARKER_RE.exec(lines[i]);
+        if (match)
+            map.set(match[1], i);
+    }
+    return map;
+}
+/**
+ * Correlate index blocks (line anchors + ids) with `<!-- commentray:block id=… -->`
+ * markers in commentray. Only `lines:` anchors with a visible
+ * marker participate. Sorted by `sourceStart`.
+ */
+export function buildBlockScrollLinks(index, sourceRelative, commentrayPath, commentrayMarkdown) {
+    const entry = index?.byCommentrayPath[commentrayPath];
+    if (!entry || entry.sourcePath !== sourceRelative || entry.blocks.length === 0)
+        return [];
+    const markerLineById = markerLineByIdFromMarkdown(commentrayMarkdown);
+    const links = [];
+    for (const block of entry.blocks) {
+        const anchor = parseAnchor(block.anchor);
+        if (anchor.kind !== "lines")
+            continue;
+        const commentrayLine = markerLineById.get(block.id);
+        if (commentrayLine === undefined)
+            continue;
+        links.push({
+            commentrayLine,
+            sourceStart: anchor.range.start,
+            sourceEnd: anchor.range.end,
+        });
+    }
+    links.sort((a, b) => a.sourceStart - b.sourceStart);
+    return links;
+}
+/**
+ * Choose which commentray line (0-based) to reveal so the commentary matches
+ * the top of the source viewport. Prefers the block whose source range
+ * **contains** the top line; otherwise the nearest preceding block; if above
+ * all blocks, the first block.
+ */
+export function pickCommentrayLineForSourceScroll(blocks, topSourceLine1Based) {
+    if (blocks.length === 0)
+        return null;
+    const inside = blocks.find((b) => b.sourceStart <= topSourceLine1Based && topSourceLine1Based <= b.sourceEnd);
+    if (inside)
+        return inside.commentrayLine;
+    if (topSourceLine1Based < blocks[0].sourceStart)
+        return blocks[0].commentrayLine;
+    let best = blocks[0];
+    for (const b of blocks) {
+        if (b.sourceStart <= topSourceLine1Based)
+            best = b;
+        else
+            break;
+    }
+    return best.commentrayLine;
+}
+/**
+ * Choose a 0-based source line to reveal from the top of the commentray
+ * viewport: the block whose marker is at or above that line wins; reveal the
+ * start of its source range.
+ */
+export function pickSourceLine0ForCommentrayScroll(blocks, topCommentrayLine0Based) {
+    if (blocks.length === 0)
+        return null;
+    let best = blocks[0];
+    for (const b of blocks) {
+        if (b.commentrayLine <= topCommentrayLine0Based)
+            best = b;
+        else
+            break;
+    }
+    return best.sourceStart - 1;
+}
+//# sourceMappingURL=scroll-sync.js.map

package/dist/scroll-sync.js.map

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

package/dist/validate-project.d.ts

@@ -8,4 +8,10 @@ export type ValidationResult = {
 };
 export declare function validateProject(repoRoot: string): Promise<ValidationResult>;
 export declare function readIndex(repoRoot: string): Promise<CommentrayIndex | null>;
+/**
+ * Write the metadata index to the default location under `repoRoot`, creating
+ * the `.commentray/metadata/` directory if missing. The file is written with
+ * two-space indentation and a trailing newline so diffs are easy to read.
+ */
+export declare function writeIndex(repoRoot: string, index: CommentrayIndex): Promise<void>;
 //# sourceMappingURL=validate-project.d.ts.map

package/dist/validate-project.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-project.d.ts","sourceRoot":"","sources":["../src/validate-project.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,MAAM,MAAM,eAAe,GAAG;IAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B,CAAC;AAEF,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA2CjF;AAED,wBAAsB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAUjF"}
+{"version":3,"file":"validate-project.d.ts","sourceRoot":"","sources":["../src/validate-project.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,MAAM,MAAM,eAAe,GAAG;IAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B,CAAC;AAEF,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAyCjF;AAiBD,wBAAsB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAmBjF;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAKxF"}