@phosphorco/bb-cross-references 0.4.0 → 0.4.1

package/CONTRACT.md

@@ -370,3 +370,30 @@ insufficient. Missing authority is independently scoped partial coverage using
 `pr-family-authority-unknown`, including an all-unknown empty result; known issue
 alone is excluded without fabricated unknown. Exact-self/literal semantics stay
 unchanged, and no parser/secondary graph edge/target enumeration is added.
+
+### Rendered Brief reader destination (0.4.1)
+
+The navigation describe envelope may advertise `renderedReaderVersions: [1]`.
+After explicit negotiation, either existing ready or fallback result may add
+`reader` with literal kind `thread-brief-reader`, version `1`, owner
+`thread-brief`, path `reveal`, the exact source thread id, and a bounded opaque
+UUIDv4 token. Existing proof, source-file, frame, line and fallback meanings do
+not change. Older clients continue using the fixed native file preview.
+
+`encodeBriefReaderPath` constructs only the declared same-origin native plugin
+route; `decodeBriefReaderPath` accepts only that exact path grammar. Consumers
+must project known fields and use the shared codec, never an arbitrary returned
+href, scheme, origin, owner or panel. A malformed, unnegotiated or cross-thread
+destination cannot grant another navigation target. Primary dispatch remains
+owned by the existing one-surface intent generation. Modifier/auxiliary/menu
+navigation retains the semantic fixed native FileLink.
+
+The opaque token is a presentation handle, not access authority. The Thread
+Brief owner binds it to the original input and accepted record, and checks the
+accepted/displayed raw revision, frame and section again before scrolling its
+own section ref. Missing, expired, withheld, changed or ambiguous selections
+open the known thread's brief at TOP with a short note, or honestly report
+unavailability; they never relocate by heading text. The route provides a back
+to thread action, is lazy, and reuses the accepted reader service and rendering
+without a second parser or recognition pipeline. Dispatch/conformance is not
+proof that the native rendered heading is visible; that requires live proof.

package/README.md

@@ -81,3 +81,8 @@ fixture; it never supplies a fake freshness proof. Explicitly compile
 ESM imports and physical roots; resolver fixtures are not package/registry proof.
 See CONTRACT.md for display withholding, bounds, revision fencing and the still
 separate TB raw-reader/public navigation adoption duties.
+
+In 0.4.1, Brief navigation can negotiate a rendered Thread Brief reader route.
+The optional fixed destination and shared path codec preserve the existing
+same-revision proof and native-file fallback. The reader owner validates the
+accepted section again; stale or expired selections stay at the top with a note.

package/dist/bb.js

@@ -1009,12 +1009,27 @@ function createProducerSchemas(projection) {
     [PRODUCER_METHODS.reportStatus]: { input: producerReportStatusInputSchema, output: z2.object({ version: z2.literal(1), outcome: z2.enum(["recorded", "duplicate", "stale", "conflict", "cas-mismatch"]), state: producerStateSchema }).passthrough() }
   };
 }
+var BRIEF_READER_ROUTE = Object.freeze({ kind: "thread-brief-reader", version: 1, owner: "thread-brief", path: "reveal" });
+var briefReaderDestinationSchema = z2.object({ kind: z2.literal(BRIEF_READER_ROUTE.kind), version: z2.literal(1), owner: z2.literal(BRIEF_READER_ROUTE.owner), path: z2.literal(BRIEF_READER_ROUTE.path), threadId: z2.string().regex(/^thr_[23456789abcdefghijkmnpqrstuvwxyz]{10}$/u), token: z2.string().regex(/^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/u) }).passthrough();
+function encodeBriefReaderPath(raw) {
+  const d = briefReaderDestinationSchema.parse(raw);
+  return `/plugins/${BRIEF_READER_ROUTE.owner}/${BRIEF_READER_ROUTE.path}/v1/${d.threadId}/${d.token}`;
+}
+function decodeBriefReaderPath(path) {
+  if (path.length > 256)
+    return null;
+  const match = /^\/plugins\/thread-brief\/reveal\/v1\/(thr_[23456789abcdefghijkmnpqrstuvwxyz]{10})\/([a-f0-9-]{36})$/u.exec(path);
+  if (!match)
+    return null;
+  const parsed = briefReaderDestinationSchema.safeParse({ ...BRIEF_READER_ROUTE, threadId: match[1], token: match[2] });
+  return parsed.success ? parsed.data : null;
+}
 var briefNavigationInputSchema = z2.strictObject({ version: z2.literal(1), sourceFile: briefFileSchema, sourceContentRevision: digest, frame: briefFrameSchema, section: z2.strictObject({ heading: briefHeadingSchema, originalLine: positive }) });
 var briefNavigationOutputSchema = z2.discriminatedUnion("state", [
-  z2.object({ version: z2.literal(1), state: z2.literal("ready"), sourceFile: briefFileSchema.passthrough(), sourceContentRevision: digest, location: z2.object({ kind: z2.literal("line"), line: positive, column: z2.null() }).passthrough(), proof: z2.object({ kind: z2.literal("accepted-revision-revalidated"), acceptedRevision: digest, selection: z2.literal("same-revision"), frame: briefFrameSchema.safeExtend({ bodyBase: briefFrameSchema.shape.bodyBase.passthrough(), lineMapping: briefFrameSchema.shape.lineMapping.passthrough() }).passthrough() }).passthrough() }).passthrough(),
-  z2.object({ version: z2.literal(1), state: z2.literal("fallback"), sourceFile: briefFileSchema.passthrough(), location: z2.null(), reason: z2.enum(["stale", "no-accepted-document", "ambiguous", "heading-unavailable", "source-unavailable", "over-limit"]) }).passthrough()
+  z2.object({ version: z2.literal(1), state: z2.literal("ready"), sourceFile: briefFileSchema.passthrough(), sourceContentRevision: digest, location: z2.object({ kind: z2.literal("line"), line: positive, column: z2.null() }).passthrough(), proof: z2.object({ kind: z2.literal("accepted-revision-revalidated"), acceptedRevision: digest, selection: z2.literal("same-revision"), frame: briefFrameSchema.safeExtend({ bodyBase: briefFrameSchema.shape.bodyBase.passthrough(), lineMapping: briefFrameSchema.shape.lineMapping.passthrough() }).passthrough() }).passthrough(), reader: briefReaderDestinationSchema.optional() }).passthrough(),
+  z2.object({ version: z2.literal(1), state: z2.literal("fallback"), sourceFile: briefFileSchema.passthrough(), location: z2.null(), reason: z2.enum(["stale", "no-accepted-document", "ambiguous", "heading-unavailable", "source-unavailable", "over-limit"]), reader: briefReaderDestinationSchema.optional() }).passthrough()
 ]);
-var briefNavigationDescribeOutputSchema = z2.object({ protocol: z2.literal("thread-brief-navigation"), versions: z2.array(positive).max(16) }).passthrough();
+var briefNavigationDescribeOutputSchema = z2.object({ protocol: z2.literal("thread-brief-navigation"), versions: z2.array(positive).max(16), renderedReaderVersions: z2.array(positive).max(16).optional() }).passthrough();
 var briefNavigationRpcSchemas = { [BRIEF_NAVIGATION_METHODS.describe]: { input: z2.null(), output: briefNavigationDescribeOutputSchema }, [BRIEF_NAVIGATION_METHODS.resolve]: { input: briefNavigationInputSchema, output: briefNavigationOutputSchema } };
 var outWithheld = (display) => withheld(display).passthrough();
 var briefHeadingOutputSchema = z2.union([z2.null(), z2.object({ state: z2.literal("named"), text: bytes(256) }).passthrough(), outWithheld("Heading withheld")]);
@@ -1029,6 +1044,8 @@ function validateBriefNavigationResultV1(input, raw) {
   const value = briefNavigationOutputSchema.parse(raw), file = value.sourceFile;
   if (file.kind !== input.sourceFile.kind || file.threadId !== input.sourceFile.threadId || file.path !== input.sourceFile.path)
     throw new Error("Brief navigation target mismatch.");
+  if (value.reader && value.reader.threadId !== input.sourceFile.threadId)
+    throw new Error("Brief reader target mismatch.");
   if (value.state === "ready" && (value.sourceContentRevision !== input.sourceContentRevision || value.proof.acceptedRevision !== input.sourceContentRevision || canonicalJson2(knownFrame(value.proof.frame)) !== canonicalJson2(knownFrame(input.frame)) || value.location.line !== input.section.originalLine || value.location.line > input.frame.lineMapping.fileLineCount))
     throw new Error("Brief navigation proof mismatch.");
   return value;
@@ -1730,15 +1747,19 @@ function createCrossReferencesProducerClient(sdk, pluginId = CROSS_REFERENCES_PL
 }
 function createBriefNavigationClient(sdk, options = {}) {
   const call = boundedFamilyCall(sdk, "thread-brief", options);
+  let reader = false;
   return {
     async describe(signal) {
       const d = await call(BRIEF_NAVIGATION_METHODS.describe, null, ns[BRIEF_NAVIGATION_METHODS.describe].input, ns[BRIEF_NAVIGATION_METHODS.describe].output, 8192, 16384, signal);
       if (!d.versions.includes(1))
         throw new CrossReferencesProtocolError("Brief navigation unavailable.");
+      reader = d.renderedReaderVersions?.includes(1) === true;
       return d;
     },
     async resolve(input, signal) {
       const value = await call(BRIEF_NAVIGATION_METHODS.resolve, input, ns[BRIEF_NAVIGATION_METHODS.resolve].input, ns[BRIEF_NAVIGATION_METHODS.resolve].output, 8192, 16384, signal);
+      if (value.reader && !reader)
+        throw new CrossReferencesProtocolError("Brief reader destination was not negotiated.");
       return validateBriefNavigationResultV1(input, value);
     }
   };

package/dist/index.js

@@ -1009,12 +1009,27 @@ function createProducerSchemas(projection) {
     [PRODUCER_METHODS.reportStatus]: { input: producerReportStatusInputSchema, output: z2.object({ version: z2.literal(1), outcome: z2.enum(["recorded", "duplicate", "stale", "conflict", "cas-mismatch"]), state: producerStateSchema }).passthrough() }
   };
 }
+var BRIEF_READER_ROUTE = Object.freeze({ kind: "thread-brief-reader", version: 1, owner: "thread-brief", path: "reveal" });
+var briefReaderDestinationSchema = z2.object({ kind: z2.literal(BRIEF_READER_ROUTE.kind), version: z2.literal(1), owner: z2.literal(BRIEF_READER_ROUTE.owner), path: z2.literal(BRIEF_READER_ROUTE.path), threadId: z2.string().regex(/^thr_[23456789abcdefghijkmnpqrstuvwxyz]{10}$/u), token: z2.string().regex(/^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/u) }).passthrough();
+function encodeBriefReaderPath(raw) {
+  const d = briefReaderDestinationSchema.parse(raw);
+  return `/plugins/${BRIEF_READER_ROUTE.owner}/${BRIEF_READER_ROUTE.path}/v1/${d.threadId}/${d.token}`;
+}
+function decodeBriefReaderPath(path) {
+  if (path.length > 256)
+    return null;
+  const match = /^\/plugins\/thread-brief\/reveal\/v1\/(thr_[23456789abcdefghijkmnpqrstuvwxyz]{10})\/([a-f0-9-]{36})$/u.exec(path);
+  if (!match)
+    return null;
+  const parsed = briefReaderDestinationSchema.safeParse({ ...BRIEF_READER_ROUTE, threadId: match[1], token: match[2] });
+  return parsed.success ? parsed.data : null;
+}
 var briefNavigationInputSchema = z2.strictObject({ version: z2.literal(1), sourceFile: briefFileSchema, sourceContentRevision: digest, frame: briefFrameSchema, section: z2.strictObject({ heading: briefHeadingSchema, originalLine: positive }) });
 var briefNavigationOutputSchema = z2.discriminatedUnion("state", [
-  z2.object({ version: z2.literal(1), state: z2.literal("ready"), sourceFile: briefFileSchema.passthrough(), sourceContentRevision: digest, location: z2.object({ kind: z2.literal("line"), line: positive, column: z2.null() }).passthrough(), proof: z2.object({ kind: z2.literal("accepted-revision-revalidated"), acceptedRevision: digest, selection: z2.literal("same-revision"), frame: briefFrameSchema.safeExtend({ bodyBase: briefFrameSchema.shape.bodyBase.passthrough(), lineMapping: briefFrameSchema.shape.lineMapping.passthrough() }).passthrough() }).passthrough() }).passthrough(),
-  z2.object({ version: z2.literal(1), state: z2.literal("fallback"), sourceFile: briefFileSchema.passthrough(), location: z2.null(), reason: z2.enum(["stale", "no-accepted-document", "ambiguous", "heading-unavailable", "source-unavailable", "over-limit"]) }).passthrough()
+  z2.object({ version: z2.literal(1), state: z2.literal("ready"), sourceFile: briefFileSchema.passthrough(), sourceContentRevision: digest, location: z2.object({ kind: z2.literal("line"), line: positive, column: z2.null() }).passthrough(), proof: z2.object({ kind: z2.literal("accepted-revision-revalidated"), acceptedRevision: digest, selection: z2.literal("same-revision"), frame: briefFrameSchema.safeExtend({ bodyBase: briefFrameSchema.shape.bodyBase.passthrough(), lineMapping: briefFrameSchema.shape.lineMapping.passthrough() }).passthrough() }).passthrough(), reader: briefReaderDestinationSchema.optional() }).passthrough(),
+  z2.object({ version: z2.literal(1), state: z2.literal("fallback"), sourceFile: briefFileSchema.passthrough(), location: z2.null(), reason: z2.enum(["stale", "no-accepted-document", "ambiguous", "heading-unavailable", "source-unavailable", "over-limit"]), reader: briefReaderDestinationSchema.optional() }).passthrough()
 ]);
-var briefNavigationDescribeOutputSchema = z2.object({ protocol: z2.literal("thread-brief-navigation"), versions: z2.array(positive).max(16) }).passthrough();
+var briefNavigationDescribeOutputSchema = z2.object({ protocol: z2.literal("thread-brief-navigation"), versions: z2.array(positive).max(16), renderedReaderVersions: z2.array(positive).max(16).optional() }).passthrough();
 var briefNavigationRpcSchemas = { [BRIEF_NAVIGATION_METHODS.describe]: { input: z2.null(), output: briefNavigationDescribeOutputSchema }, [BRIEF_NAVIGATION_METHODS.resolve]: { input: briefNavigationInputSchema, output: briefNavigationOutputSchema } };
 var outWithheld = (display) => withheld(display).passthrough();
 var briefHeadingOutputSchema = z2.union([z2.null(), z2.object({ state: z2.literal("named"), text: bytes(256) }).passthrough(), outWithheld("Heading withheld")]);
@@ -1029,6 +1044,8 @@ function validateBriefNavigationResultV1(input, raw) {
   const value = briefNavigationOutputSchema.parse(raw), file = value.sourceFile;
   if (file.kind !== input.sourceFile.kind || file.threadId !== input.sourceFile.threadId || file.path !== input.sourceFile.path)
     throw new Error("Brief navigation target mismatch.");
+  if (value.reader && value.reader.threadId !== input.sourceFile.threadId)
+    throw new Error("Brief reader target mismatch.");
   if (value.state === "ready" && (value.sourceContentRevision !== input.sourceContentRevision || value.proof.acceptedRevision !== input.sourceContentRevision || canonicalJson2(knownFrame(value.proof.frame)) !== canonicalJson2(knownFrame(input.frame)) || value.location.line !== input.section.originalLine || value.location.line > input.frame.lineMapping.fileLineCount))
     throw new Error("Brief navigation proof mismatch.");
   return value;
@@ -1554,9 +1571,11 @@ export {
   forwardReferenceStatusSchema,
   excerptV2Schema,
   excerptRecordV2Schema,
+  encodeBriefReaderPath,
   describeOutputSchema,
   describeInputSchema,
   defaultPageSize,
+  decodeBriefReaderPath,
   crossReferencesV2RpcSchemas,
   crossReferencesRpcSchemas,
   crossReferencesProducerRpcSchemas,
@@ -1575,6 +1594,7 @@ export {
   briefStatusDigest,
   briefSourcePresentationSchema,
   briefSourceLabelSchema,
+  briefReaderDestinationSchema,
   briefProvenanceSchema,
   briefProvenanceOutputSchema,
   briefPresentation,
@@ -1631,6 +1651,7 @@ export {
   CROSS_REFERENCES_PROTOCOL,
   CROSS_REFERENCES_PLUGIN_ID,
   BriefAdmissionError,
+  BRIEF_READER_ROUTE,
   BRIEF_NAVIGATION_METHODS,
   BRIEF_LIMIT_CODES,
   BRIEF_LIMITS

package/dist/react.js

@@ -1009,12 +1009,27 @@ function createProducerSchemas(projection) {
     [PRODUCER_METHODS.reportStatus]: { input: producerReportStatusInputSchema, output: z2.object({ version: z2.literal(1), outcome: z2.enum(["recorded", "duplicate", "stale", "conflict", "cas-mismatch"]), state: producerStateSchema }).passthrough() }
   };
 }
+var BRIEF_READER_ROUTE = Object.freeze({ kind: "thread-brief-reader", version: 1, owner: "thread-brief", path: "reveal" });
+var briefReaderDestinationSchema = z2.object({ kind: z2.literal(BRIEF_READER_ROUTE.kind), version: z2.literal(1), owner: z2.literal(BRIEF_READER_ROUTE.owner), path: z2.literal(BRIEF_READER_ROUTE.path), threadId: z2.string().regex(/^thr_[23456789abcdefghijkmnpqrstuvwxyz]{10}$/u), token: z2.string().regex(/^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/u) }).passthrough();
+function encodeBriefReaderPath(raw) {
+  const d = briefReaderDestinationSchema.parse(raw);
+  return `/plugins/${BRIEF_READER_ROUTE.owner}/${BRIEF_READER_ROUTE.path}/v1/${d.threadId}/${d.token}`;
+}
+function decodeBriefReaderPath(path) {
+  if (path.length > 256)
+    return null;
+  const match = /^\/plugins\/thread-brief\/reveal\/v1\/(thr_[23456789abcdefghijkmnpqrstuvwxyz]{10})\/([a-f0-9-]{36})$/u.exec(path);
+  if (!match)
+    return null;
+  const parsed = briefReaderDestinationSchema.safeParse({ ...BRIEF_READER_ROUTE, threadId: match[1], token: match[2] });
+  return parsed.success ? parsed.data : null;
+}
 var briefNavigationInputSchema = z2.strictObject({ version: z2.literal(1), sourceFile: briefFileSchema, sourceContentRevision: digest, frame: briefFrameSchema, section: z2.strictObject({ heading: briefHeadingSchema, originalLine: positive }) });
 var briefNavigationOutputSchema = z2.discriminatedUnion("state", [
-  z2.object({ version: z2.literal(1), state: z2.literal("ready"), sourceFile: briefFileSchema.passthrough(), sourceContentRevision: digest, location: z2.object({ kind: z2.literal("line"), line: positive, column: z2.null() }).passthrough(), proof: z2.object({ kind: z2.literal("accepted-revision-revalidated"), acceptedRevision: digest, selection: z2.literal("same-revision"), frame: briefFrameSchema.safeExtend({ bodyBase: briefFrameSchema.shape.bodyBase.passthrough(), lineMapping: briefFrameSchema.shape.lineMapping.passthrough() }).passthrough() }).passthrough() }).passthrough(),
-  z2.object({ version: z2.literal(1), state: z2.literal("fallback"), sourceFile: briefFileSchema.passthrough(), location: z2.null(), reason: z2.enum(["stale", "no-accepted-document", "ambiguous", "heading-unavailable", "source-unavailable", "over-limit"]) }).passthrough()
+  z2.object({ version: z2.literal(1), state: z2.literal("ready"), sourceFile: briefFileSchema.passthrough(), sourceContentRevision: digest, location: z2.object({ kind: z2.literal("line"), line: positive, column: z2.null() }).passthrough(), proof: z2.object({ kind: z2.literal("accepted-revision-revalidated"), acceptedRevision: digest, selection: z2.literal("same-revision"), frame: briefFrameSchema.safeExtend({ bodyBase: briefFrameSchema.shape.bodyBase.passthrough(), lineMapping: briefFrameSchema.shape.lineMapping.passthrough() }).passthrough() }).passthrough(), reader: briefReaderDestinationSchema.optional() }).passthrough(),
+  z2.object({ version: z2.literal(1), state: z2.literal("fallback"), sourceFile: briefFileSchema.passthrough(), location: z2.null(), reason: z2.enum(["stale", "no-accepted-document", "ambiguous", "heading-unavailable", "source-unavailable", "over-limit"]), reader: briefReaderDestinationSchema.optional() }).passthrough()
 ]);
-var briefNavigationDescribeOutputSchema = z2.object({ protocol: z2.literal("thread-brief-navigation"), versions: z2.array(positive).max(16) }).passthrough();
+var briefNavigationDescribeOutputSchema = z2.object({ protocol: z2.literal("thread-brief-navigation"), versions: z2.array(positive).max(16), renderedReaderVersions: z2.array(positive).max(16).optional() }).passthrough();
 var briefNavigationRpcSchemas = { [BRIEF_NAVIGATION_METHODS.describe]: { input: z2.null(), output: briefNavigationDescribeOutputSchema }, [BRIEF_NAVIGATION_METHODS.resolve]: { input: briefNavigationInputSchema, output: briefNavigationOutputSchema } };
 var outWithheld = (display) => withheld(display).passthrough();
 var briefHeadingOutputSchema = z2.union([z2.null(), z2.object({ state: z2.literal("named"), text: bytes(256) }).passthrough(), outWithheld("Heading withheld")]);
@@ -1029,6 +1044,8 @@ function validateBriefNavigationResultV1(input, raw) {
   const value = briefNavigationOutputSchema.parse(raw), file = value.sourceFile;
   if (file.kind !== input.sourceFile.kind || file.threadId !== input.sourceFile.threadId || file.path !== input.sourceFile.path)
     throw new Error("Brief navigation target mismatch.");
+  if (value.reader && value.reader.threadId !== input.sourceFile.threadId)
+    throw new Error("Brief reader target mismatch.");
   if (value.state === "ready" && (value.sourceContentRevision !== input.sourceContentRevision || value.proof.acceptedRevision !== input.sourceContentRevision || canonicalJson2(knownFrame(value.proof.frame)) !== canonicalJson2(knownFrame(input.frame)) || value.location.line !== input.section.originalLine || value.location.line > input.frame.lineMapping.fileLineCount))
     throw new Error("Brief navigation proof mismatch.");
   return value;

package/dist/testing.js

@@ -103,7 +103,15 @@ async function runBriefNavigationConformance(options) {
   await client.describe();
   const result = await client.resolve(options.input);
   await options.assertResult(result);
-  return { level: "source-conformance", pluginId: "thread-brief", checks: ["navigation-describe", "fixed-file-same-revision-proof"] };
+  const checks = ["navigation-describe", "fixed-file-same-revision-proof"];
+  if (result.reader) {
+    const { encodeBriefReaderPath, decodeBriefReaderPath } = await import("./index.js");
+    const decoded = decodeBriefReaderPath(encodeBriefReaderPath(result.reader));
+    if (!decoded || decoded.threadId !== options.input.sourceFile.threadId || decoded.token !== result.reader.token)
+      throw new Error("Rendered Brief destination roundtrip failed.");
+    checks.push("declared-rendered-reader-destination");
+  }
+  return { level: "source-conformance", pluginId: "thread-brief", checks };
 }
 export {
   runCrossReferencesV2Conformance,

package/dist/types/bb.d.ts

@@ -1502,6 +1502,7 @@ declare const ps: {
         readonly output: z.ZodObject<{
             protocol: z.ZodLiteral<"thread-brief-navigation">;
             versions: z.ZodArray<z.ZodNumber>;
+            renderedReaderVersions: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
         }, z.core.$loose>;
     };
     readonly threadBriefNavigationV1ResolveHeading: {
@@ -1578,6 +1579,14 @@ declare const ps: {
                     }, z.core.$loose>;
                 }, z.core.$loose>;
             }, z.core.$loose>;
+            reader: z.ZodOptional<z.ZodObject<{
+                kind: z.ZodLiteral<"thread-brief-reader">;
+                version: z.ZodLiteral<1>;
+                owner: z.ZodLiteral<"thread-brief">;
+                path: z.ZodLiteral<"reveal">;
+                threadId: z.ZodString;
+                token: z.ZodString;
+            }, z.core.$loose>>;
         }, z.core.$loose>, z.ZodObject<{
             version: z.ZodLiteral<1>;
             state: z.ZodLiteral<"fallback">;
@@ -1595,6 +1604,14 @@ declare const ps: {
                 "heading-unavailable": "heading-unavailable";
                 "source-unavailable": "source-unavailable";
             }>;
+            reader: z.ZodOptional<z.ZodObject<{
+                kind: z.ZodLiteral<"thread-brief-reader">;
+                version: z.ZodLiteral<1>;
+                owner: z.ZodLiteral<"thread-brief">;
+                path: z.ZodLiteral<"reveal">;
+                threadId: z.ZodString;
+                token: z.ZodString;
+            }, z.core.$loose>>;
         }, z.core.$loose>], "state">;
     };
 };
@@ -2709,10 +2726,12 @@ export declare const briefNavigationRpcContract: {
             [x: string]: unknown;
             protocol: "thread-brief-navigation";
             versions: number[];
+            renderedReaderVersions?: number[] | undefined;
         }, {
             [x: string]: unknown;
             protocol: "thread-brief-navigation";
             versions: number[];
+            renderedReaderVersions?: number[] | undefined;
         }>;
     };
     readonly threadBriefNavigationV1ResolveHeading: {
@@ -2828,6 +2847,15 @@ export declare const briefNavigationRpcContract: {
                     };
                 };
             };
+            reader?: {
+                [x: string]: unknown;
+                kind: "thread-brief-reader";
+                version: 1;
+                owner: "thread-brief";
+                path: "reveal";
+                threadId: string;
+                token: string;
+            } | undefined;
         } | {
             [x: string]: unknown;
             version: 1;
@@ -2840,6 +2868,15 @@ export declare const briefNavigationRpcContract: {
             };
             location: null;
             reason: "stale" | "over-limit" | "no-accepted-document" | "ambiguous" | "heading-unavailable" | "source-unavailable";
+            reader?: {
+                [x: string]: unknown;
+                kind: "thread-brief-reader";
+                version: 1;
+                owner: "thread-brief";
+                path: "reveal";
+                threadId: string;
+                token: string;
+            } | undefined;
         }, {
             [x: string]: unknown;
             version: 1;
@@ -2881,6 +2918,15 @@ export declare const briefNavigationRpcContract: {
                     };
                 };
             };
+            reader?: {
+                [x: string]: unknown;
+                kind: "thread-brief-reader";
+                version: 1;
+                owner: "thread-brief";
+                path: "reveal";
+                threadId: string;
+                token: string;
+            } | undefined;
         } | {
             [x: string]: unknown;
             version: 1;
@@ -2893,6 +2939,15 @@ export declare const briefNavigationRpcContract: {
             };
             location: null;
             reason: "stale" | "over-limit" | "no-accepted-document" | "ambiguous" | "heading-unavailable" | "source-unavailable";
+            reader?: {
+                [x: string]: unknown;
+                kind: "thread-brief-reader";
+                version: 1;
+                owner: "thread-brief";
+                path: "reveal";
+                threadId: string;
+                token: string;
+            } | undefined;
         }>;
     };
 };
@@ -3165,6 +3220,7 @@ export declare function createBriefNavigationClient(sdk: CrossReferencesSdk, opt
         [x: string]: unknown;
         protocol: "thread-brief-navigation";
         versions: number[];
+        renderedReaderVersions?: number[] | undefined;
     }>;
     resolve(input: BriefNavigationInput, signal?: AbortSignal): Promise<{
         [x: string]: unknown;
@@ -3207,6 +3263,15 @@ export declare function createBriefNavigationClient(sdk: CrossReferencesSdk, opt
                 };
             };
         };
+        reader?: {
+            [x: string]: unknown;
+            kind: "thread-brief-reader";
+            version: 1;
+            owner: "thread-brief";
+            path: "reveal";
+            threadId: string;
+            token: string;
+        } | undefined;
     } | {
         [x: string]: unknown;
         version: 1;
@@ -3219,6 +3284,15 @@ export declare function createBriefNavigationClient(sdk: CrossReferencesSdk, opt
         };
         location: null;
         reason: "stale" | "over-limit" | "no-accepted-document" | "ambiguous" | "heading-unavailable" | "source-unavailable";
+        reader?: {
+            [x: string]: unknown;
+            kind: "thread-brief-reader";
+            version: 1;
+            owner: "thread-brief";
+            path: "reveal";
+            threadId: string;
+            token: string;
+        } | undefined;
     }>;
 };
 export {};

package/dist/types/producer.d.ts

@@ -1904,6 +1904,25 @@ export type ProducerReportStatusOutput = {
     outcome: 'recorded' | 'duplicate' | 'stale' | 'conflict' | 'cas-mismatch';
     state: ProducerState;
 };
+/** A declared native plugin route, never an arbitrary href. Only these known
+ * fields participate in navigation; additive output fields are ignored. */
+export declare const BRIEF_READER_ROUTE: Readonly<{
+    readonly kind: "thread-brief-reader";
+    readonly version: 1;
+    readonly owner: "thread-brief";
+    readonly path: "reveal";
+}>;
+export declare const briefReaderDestinationSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"thread-brief-reader">;
+    version: z.ZodLiteral<1>;
+    owner: z.ZodLiteral<"thread-brief">;
+    path: z.ZodLiteral<"reveal">;
+    threadId: z.ZodString;
+    token: z.ZodString;
+}, z.core.$loose>;
+export type BriefReaderDestination = z.infer<typeof briefReaderDestinationSchema>;
+export declare function encodeBriefReaderPath(raw: BriefReaderDestination): string;
+export declare function decodeBriefReaderPath(path: string): BriefReaderDestination | null;
 export declare const briefNavigationInputSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
     sourceFile: z.ZodObject<{
@@ -1977,6 +1996,14 @@ export declare const briefNavigationOutputSchema: z.ZodDiscriminatedUnion<[z.Zod
             }, z.core.$loose>;
         }, z.core.$loose>;
     }, z.core.$loose>;
+    reader: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodLiteral<"thread-brief-reader">;
+        version: z.ZodLiteral<1>;
+        owner: z.ZodLiteral<"thread-brief">;
+        path: z.ZodLiteral<"reveal">;
+        threadId: z.ZodString;
+        token: z.ZodString;
+    }, z.core.$loose>>;
 }, z.core.$loose>, z.ZodObject<{
     version: z.ZodLiteral<1>;
     state: z.ZodLiteral<"fallback">;
@@ -1994,10 +2021,19 @@ export declare const briefNavigationOutputSchema: z.ZodDiscriminatedUnion<[z.Zod
         "heading-unavailable": "heading-unavailable";
         "source-unavailable": "source-unavailable";
     }>;
+    reader: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodLiteral<"thread-brief-reader">;
+        version: z.ZodLiteral<1>;
+        owner: z.ZodLiteral<"thread-brief">;
+        path: z.ZodLiteral<"reveal">;
+        threadId: z.ZodString;
+        token: z.ZodString;
+    }, z.core.$loose>>;
 }, z.core.$loose>], "state">;
 export declare const briefNavigationDescribeOutputSchema: z.ZodObject<{
     protocol: z.ZodLiteral<"thread-brief-navigation">;
     versions: z.ZodArray<z.ZodNumber>;
+    renderedReaderVersions: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
 }, z.core.$loose>;
 export declare const briefNavigationRpcSchemas: {
     readonly "threadBriefNavigation.describe": {
@@ -2005,6 +2041,7 @@ export declare const briefNavigationRpcSchemas: {
         readonly output: z.ZodObject<{
             protocol: z.ZodLiteral<"thread-brief-navigation">;
             versions: z.ZodArray<z.ZodNumber>;
+            renderedReaderVersions: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
         }, z.core.$loose>;
     };
     readonly threadBriefNavigationV1ResolveHeading: {
@@ -2081,6 +2118,14 @@ export declare const briefNavigationRpcSchemas: {
                     }, z.core.$loose>;
                 }, z.core.$loose>;
             }, z.core.$loose>;
+            reader: z.ZodOptional<z.ZodObject<{
+                kind: z.ZodLiteral<"thread-brief-reader">;
+                version: z.ZodLiteral<1>;
+                owner: z.ZodLiteral<"thread-brief">;
+                path: z.ZodLiteral<"reveal">;
+                threadId: z.ZodString;
+                token: z.ZodString;
+            }, z.core.$loose>>;
         }, z.core.$loose>, z.ZodObject<{
             version: z.ZodLiteral<1>;
             state: z.ZodLiteral<"fallback">;
@@ -2098,6 +2143,14 @@ export declare const briefNavigationRpcSchemas: {
                 "heading-unavailable": "heading-unavailable";
                 "source-unavailable": "source-unavailable";
             }>;
+            reader: z.ZodOptional<z.ZodObject<{
+                kind: z.ZodLiteral<"thread-brief-reader">;
+                version: z.ZodLiteral<1>;
+                owner: z.ZodLiteral<"thread-brief">;
+                path: z.ZodLiteral<"reveal">;
+                threadId: z.ZodString;
+                token: z.ZodString;
+            }, z.core.$loose>>;
         }, z.core.$loose>], "state">;
     };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phosphorco/bb-cross-references",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "type": "module",
   "license": "MIT",
   "description": "Shared Cross References v1 codecs, explicit clients, and reference controls.",
@@ -76,7 +76,7 @@
     "react": "19.2.1",
     "react-dom": "19.2.1",
     "typescript": "5.9.3",
-    "jsdom": "26.1.0",
+    "jsdom": "^27.0.0",
     "@types/jsdom": "21.1.7"
   },
   "scripts": {