Question
", back: "Answer
" }]); const read = createReader({ bucket: {} as R2Bucket, - getDocumentSession: () => createDocumentSession({ html: "", revision: "unused" }), + getDocumentSession: () => createDocumentSession({ html: "" }), item: flashcardItem, readFlashcardItem: async () => ({ cards: set.cards, @@ -75,15 +77,14 @@ describe("WorkspaceContentReader", () => { { cards: [ { - cardId: set.cards[0]!.id, - revision: expect.stringMatching(/^[A-Za-z0-9_-]{10}$/), + ref: expect.stringMatching(unitRefPattern), front: "Question
", back: "Answer
", study: { lastRating: "good", reviewCount: 2 }, }, ], format: "html", - location: { kind: "cards", returned: [1], total: 1 }, + location: { kind: "entries", returned: [1], total: 1 }, progress: { gotItCount: 1, missedCount: 0, @@ -91,104 +92,85 @@ describe("WorkspaceContentReader", () => { totalCards: 1, unreviewedCount: 0, }, + ref: "refcard1", status: "ready", type: "flashcard", }, ]); }); - it("reads the current flashcard addressed by a ref", async () => { + it("reads the exact flashcard an address identifies", async () => { const set = createFlashcardSetFromHtml([ { front: "One
", back: "1
" }, { front: "Two
", back: "2
" }, ]); const read = createReader({ bucket: {} as R2Bucket, - getDocumentSession: () => createDocumentSession({ html: "", revision: "unused" }), + getDocumentSession: () => createDocumentSession({ html: "" }), item: flashcardItem, readFlashcardItem: async () => ({ cards: set.cards, studyState: { kind: "flashcard", cards: {} }, }), - resolveReference: (_itemId, ref) => - ref === "wr_AAAAAAAA" - ? { - cardId: set.cards[1]!.id, - itemId: flashcardItem.id, - kind: "flashcard", - version: 1, - } + resolveRefKey: async (refKey) => + refKey === flashcardItem.refKey + ? { item: flashcardItem, path: "/Biology cards" } : undefined, }); await expect( - read([{ mode: "ref", path: "/Biology cards", ref: "wr_AAAAAAAA" }]), + read([{ mode: "ref", ref: `refcard1/${set.cards[1]!.id}` }]), ).resolves.toMatchObject([ { - cards: [{ cardId: set.cards[1]!.id, front: "Two
" }], - location: { kind: "cards", returned: [2], total: 2 }, + cards: [{ front: "Two
" }], + location: { kind: "entries", returned: [2], total: 2 }, status: "ready", type: "flashcard", }, ]); }); - it("continues a large flashcard set without repeating cards", async () => { + it("chunks a large flashcard set and continues by entry range", async () => { const side = `${"x".repeat(7_900)}
`; const set = createFlashcardSetFromHtml( Array.from({ length: 4 }, () => ({ front: side, back: side })), ); - let cards = set.cards; const read = createReader({ bucket: {} as R2Bucket, - getDocumentSession: () => createDocumentSession({ html: "", revision: "unused" }), + getDocumentSession: () => createDocumentSession({ html: "" }), item: flashcardItem, readFlashcardItem: async () => ({ - cards, + cards: set.cards, studyState: { kind: "flashcard", cards: {} }, }), }); const [first] = await read([{ mode: "start", path: "/Biology cards" }]); expect(first).toMatchObject({ - cards: expect.any(Array), - location: { kind: "cards", returned: [1, 2, 3], total: 4 }, + location: { kind: "entries", returned: [1, 2, 3], total: 4 }, status: "ready", type: "flashcard", }); - if (!first || first.status !== "ready" || first.type !== "flashcard" || !first.nextCursor) { - throw new Error("Expected the first flashcard chunk to have a continuation cursor."); - } - expect(first.cards).toHaveLength(3); - - cards = [...set.cards].reverse(); - await expect( - read([{ cursor: first.nextCursor, mode: "continue", path: "/Biology cards" }]), - ).resolves.toEqual([{ code: "content_changed", path: "/Biology cards", status: "failed" }]); - cards = set.cards; - const [second] = await read([ - { cursor: first.nextCursor, mode: "continue", path: "/Biology cards" }, - ]); - expect(second).toMatchObject({ - cards: [{ cardId: set.cards[3]!.id, revision: expect.stringMatching(/^[A-Za-z0-9_-]{10}$/) }], - location: { kind: "cards", returned: [4], total: 4 }, + const [rest] = await read([{ mode: "entries", path: "/Biology cards", range: "4" }]); + expect(rest).toMatchObject({ + cards: [{ ref: expect.stringMatching(unitRefPattern) }], + location: { kind: "entries", returned: [4], total: 4 }, status: "ready", type: "flashcard", }); - const [targeted] = await read([{ mode: "cards", path: "/Biology cards", range: "1, 4" }]); + const [targeted] = await read([{ mode: "entries", path: "/Biology cards", range: "1, 4" }]); expect(targeted).toMatchObject({ - cards: [{ cardId: set.cards[0]!.id }, { cardId: set.cards[3]!.id }], - location: { kind: "cards", returned: [1, 4], total: 4 }, + location: { kind: "entries", returned: [1, 4], total: 4 }, status: "ready", type: "flashcard", }); }); - it("continues a large live document with a revision-guarded cursor", async () => { + it("chunks a large document and continues by block range", async () => { const html = Array.from({ length: 20_000 }, (_, index) => `line ${index + 1}
`).join(""); - const session = createDocumentSession({ html, revision: "revision-1" }); + const session = createDocumentSession({ html }); const read = createReader({ bucket: {} as R2Bucket, getDocumentSession: () => session, @@ -199,6 +181,7 @@ describe("WorkspaceContentReader", () => { format: "html", location: { kind: "blocks", startBlock: 1, totalBlocks: 20_000 }, path: "/Notes", + ref: "refdoc01", status: "ready", type: "document", }); @@ -206,55 +189,46 @@ describe("WorkspaceContentReader", () => { !first || first.status !== "ready" || first.type !== "document" || - first.location.kind !== "blocks" || - !first.nextCursor + first.location.kind !== "blocks" ) { - throw new Error("Expected the first document chunk to have a continuation cursor."); + throw new Error("Expected a document chunk."); } + expect(first.location.endBlock).toBeLessThan(20_000); - const [second] = await read([{ cursor: first.nextCursor, mode: "continue", path: "/Notes" }]); + const [second] = await read([ + { + mode: "entries", + path: "/Notes", + range: `${first.location.endBlock + 1}-${first.location.endBlock + 3}`, + }, + ]); expect(second).toMatchObject({ - location: { kind: "blocks" }, - path: "/Notes", + location: { + kind: "blocks", + startBlock: first.location.endBlock + 1, + endBlock: first.location.endBlock + 3, + }, status: "ready", type: "document", }); - if ( - !second || - second.status !== "ready" || - second.type !== "document" || - second.location.kind !== "blocks" - ) { - throw new Error("Expected a continued document chunk."); - } - expect(second.location.startBlock).toBeGreaterThan(first.location.startBlock); }); - it("rejects continuation when the live document revision changed", async () => { - const session = createDocumentSession({ - html: "a
".repeat(40_000), - revision: "revision-1", - }); + it("rejects a scattered block range for documents", async () => { const read = createReader({ bucket: {} as R2Bucket, - getDocumentSession: () => session, + getDocumentSession: () => createDocumentSession({ html: "a
b
" }), }); - const [first] = await read([{ mode: "start", path: "/Notes" }]); - if (!first || first.status !== "ready" || first.type !== "document" || !first.nextCursor) { - throw new Error("Expected a continuation cursor."); - } - session.readHtmlChunk = vi.fn(async () => ({ status: "content_changed" })); - await expect( - read([{ cursor: first.nextCursor, mode: "continue", path: "/Notes" }]), - ).resolves.toEqual([{ code: "content_changed", path: "/Notes", status: "failed" }]); - }, 10_000); + await expect(read([{ mode: "entries", path: "/Notes", range: "1,3" }])).resolves.toMatchObject([ + { code: "invalid_selection", path: "/Notes", status: "failed" }, + ]); + }); it("keeps document HTML split on top-level block boundaries", async () => { const html = `Heading
${"x".repeat(64_000)}Tail
`; const read = createReader({ bucket: {} as R2Bucket, - getDocumentSession: () => createDocumentSession({ html, revision: "revision-1" }), + getDocumentSession: () => createDocumentSession({ html }), }); const contents: string[] = []; @@ -262,77 +236,46 @@ describe("WorkspaceContentReader", () => { for (;;) { const [result] = await read([request]); expect(result).toMatchObject({ status: "ready", type: "document" }); - if (!result || result.status !== "ready" || result.type !== "document") { + if ( + !result || + result.status !== "ready" || + result.type !== "document" || + result.location.kind !== "blocks" + ) { throw new Error("Expected a document chunk."); } contents.push(result.content); - if (!result.nextCursor) { + if (result.location.endBlock >= result.location.totalBlocks) { break; } - request = { cursor: result.nextCursor, mode: "continue", path: "/Notes" }; + request = { + mode: "entries", + path: "/Notes", + range: `${result.location.endBlock + 1}-${result.location.totalBlocks}`, + }; } expect(contents).toHaveLength(3); expect(contents[0]).toMatch( - /^Heading<\/h1>$/,
+ /^Heading<\/h1>$/,
);
expect(contents[1]).toContain("");
expect(contents[2]).toContain(">Tail");
});
- it("rejects a nonzero continuation offset for an empty document", async () => {
- const read = createReader({
- bucket: {} as R2Bucket,
- getDocumentSession: () => createDocumentSession({ html: "", revision: "revision-1" }),
- });
- const cursor = encodeWorkspaceContentCursor({
- kind: "document",
- offset: 1,
- path: "/Notes",
- revision: "revision-1",
- version: 3,
- });
-
- await expect(read([{ cursor, mode: "continue", path: "/Notes" }])).resolves.toEqual([
- { code: "invalid_cursor", path: "/Notes", status: "failed" },
- ]);
- });
-
- it("rejects a continuation cursor issued for another path", async () => {
- const read = createReader({
- bucket: {} as R2Bucket,
- getDocumentSession: () => createDocumentSession({ html: "", revision: "revision-1" }),
- });
- const cursor = encodeWorkspaceContentCursor({
- kind: "document",
- offset: 0,
- path: "/Other",
- revision: "revision-1",
- version: 3,
- });
-
- await expect(read([{ cursor, mode: "continue", path: "/Notes" }])).resolves.toEqual([
- { code: "invalid_cursor", path: "/Notes", status: "failed" },
- ]);
- });
-
it("bounds total content returned by a batch", async () => {
const read = createReader({
bucket: {} as R2Bucket,
- getDocumentSession: () =>
- createDocumentSession({
- html: `${"😀".repeat(300_000)}
`,
- revision: "revision-1",
- }),
+ getDocumentSession: () => createDocumentSession({ html: `${"😀".repeat(300_000)}
` }),
});
- const requests = Array.from({ length: 20 }, (_, index) => ({
+ const requests = Array.from({ length: 3 }, (_, index) => ({
mode: "start" as const,
path: `/Notes ${index + 1}`,
}));
const results = await read(requests);
expect(results.filter((result) => result.status === "ready")).toHaveLength(1);
- expect(results.slice(1)).toEqual(
+ expect(results.slice(1)).toMatchObject(
requests.slice(1).map((request) => ({
code: "read_budget_exceeded",
path: request.path,
@@ -346,11 +289,12 @@ describe("WorkspaceContentReader", () => {
// One session across both reads: a fresh one would mint new refs.
const session = createDocumentSession({
html: `Before
${source.replaceAll("<", "<")}`,
- revision: "revision-1",
});
const read = createReader({
bucket: {} as R2Bucket,
getDocumentSession: () => session,
+ resolveRefKey: async (refKey) =>
+ refKey === documentItem.refKey ? { item: documentItem, path: "/Notes" } : undefined,
});
const [chunk] = await read([{ mode: "start", path: "/Notes" }]);
@@ -362,21 +306,9 @@ describe("WorkspaceContentReader", () => {
const widgetTag = /]*data-type="widget"[^>]*>/.exec(chunk.content)?.[0] ?? "";
const contentRef = /data-ref="([^"]+)"/.exec(widgetTag)?.[1];
expect(contentRef).toBeTruthy();
+ const blockId = contentRef!.split(".")[0]!;
- const readBlock = createReader({
- bucket: {} as R2Bucket,
- getDocumentSession: () => session,
- resolveReference: (_itemId, ref) =>
- ref === "wr_AAAAAAAA"
- ? {
- blockId: parseDocumentAiRef(contentRef!)!,
- itemId: documentItem.id,
- kind: "document-block",
- version: 1,
- }
- : undefined,
- });
- const [block] = await readBlock([{ ref: "wr_AAAAAAAA", mode: "ref", path: "/Notes" }]);
+ const [block] = await read([{ mode: "ref", ref: `refdoc01/${blockId}` }]);
expect(block).toMatchObject({ contentRef, status: "ready", type: "block" });
if (!block || block.status !== "ready" || block.type !== "block") {
throw new Error("Expected a block read.");
@@ -385,34 +317,34 @@ describe("WorkspaceContentReader", () => {
expect(block.content).not.toContain("data-ref");
});
- it("rejects unknown exact refs", async () => {
- const fileItem = {
- ...documentItem,
- id: "file-1",
- name: "Book.pdf",
- type: "file",
- } satisfies WorkspaceItem;
+ it("rejects unknown addresses", async () => {
const read = createReader({
bucket: {} as R2Bucket,
- getDocumentSession: () => createDocumentSession({ html: "", revision: "revision-1" }),
- item: fileItem,
+ getDocumentSession: () => createDocumentSession({ html: "" }),
});
- await expect(
- read([
- {
- ref: "wr_AAAAAAAA",
- mode: "ref",
- path: "/Book.pdf",
- },
- ]),
- ).resolves.toEqual([{ code: "ref_not_found", path: "/Book.pdf", status: "failed" }]);
+ await expect(read([{ mode: "ref", ref: "zzZZzzZZ/p5" }])).resolves.toEqual([
+ { code: "ref_not_found", ref: "zzZZzzZZ/p5", status: "failed" },
+ ]);
+ });
+
+ it("rejects a unit that cannot belong to the item's type", async () => {
+ const read = createReader({
+ bucket: {} as R2Bucket,
+ getDocumentSession: () => createDocumentSession({ html: "a
" }),
+ resolveRefKey: async (refKey) =>
+ refKey === documentItem.refKey ? { item: documentItem, path: "/Notes" } : undefined,
+ });
+
+ await expect(read([{ mode: "ref", ref: "refdoc01/p5" }])).resolves.toEqual([
+ { code: "ref_not_found", ref: "refdoc01/p5", status: "failed" },
+ ]);
});
it("keeps one ordered result for every requested path", async () => {
const read = createReader({
bucket: {} as R2Bucket,
- getDocumentSession: () => createDocumentSession({ html: "", revision: "revision-1" }),
+ getDocumentSession: () => createDocumentSession({ html: "" }),
resolvePaths: vi.fn(
async () =>
[
@@ -437,18 +369,13 @@ describe("WorkspaceContentReader", () => {
});
});
-function createDocumentSession(input: { html: string; revision: string }) {
+function createDocumentSession(input: { html: string }) {
const document = ensureTiptapDocumentBlockIds(parseDocumentAiHtml(input.html)).document;
const documentNode = getTiptapDocumentSchema().nodeFromJSON(document);
return {
- readHtmlChunk: vi.fn(async ({ expectedRevision, offset }) => {
- if (expectedRevision && expectedRevision !== input.revision) {
- return { status: "content_changed" as const };
- }
- const chunk = await readDocumentHtmlChunk(documentNode, offset);
- return chunk
- ? { ...chunk, revision: input.revision, status: "ready" as const }
- : { status: "invalid_offset" as const };
+ readHtmlChunk: vi.fn(async ({ offset, maxBlocks }: { offset: number; maxBlocks?: number }) => {
+ const chunk = await readDocumentHtmlChunk(documentNode, offset, maxBlocks);
+ return chunk ? { ...chunk, status: "ready" as const } : { status: "invalid_offset" as const };
}),
readBlock: vi.fn(async ({ blockId }: { blockId: string }) => {
let found: ReturnType | null = null;
@@ -480,7 +407,8 @@ function createReader(input: {
cards: ReturnType["cards"];
studyState: FlashcardStudyState;
}>;
- resolveReference?: Parameters[0]["resolveReference"];
+ readQuizItem?: Parameters[0]["readQuizItem"];
+ resolveRefKey?: Parameters[0]["resolveRefKey"];
resolvePaths?: typeof persistence.resolveWorkspacePaths;
}) {
const item = input.item ?? documentItem;
@@ -499,7 +427,10 @@ function createReader(input: {
readFlashcardItem:
input.readFlashcardItem ??
(async () => ({ cards: [], studyState: { kind: "flashcard", cards: {} } })),
- resolveReference: input.resolveReference,
+ readQuizItem:
+ input.readQuizItem ??
+ (async () => ({ questions: [], studyState: { kind: "quiz", answers: {} } })),
+ resolveRefKey: input.resolveRefKey ?? (async () => undefined),
requests,
workspaceId: "workspace-1",
});
diff --git a/src/features/workspaces/content/workspace-content-reader.ts b/src/features/workspaces/content/workspace-content-reader.ts
index 4349e295..6119389a 100644
--- a/src/features/workspaces/content/workspace-content-reader.ts
+++ b/src/features/workspaces/content/workspace-content-reader.ts
@@ -1,8 +1,4 @@
-import {
- type WorkspaceItem,
- getWorkspaceItemContentKind,
- isWorkspaceItemContainer,
-} from "#/features/workspaces/contracts";
+import { type WorkspaceItem, isWorkspaceItemContainer } from "#/features/workspaces/contracts";
import type {
WorkspaceContentReadRequest,
WorkspaceContentReadResult,
@@ -29,24 +25,35 @@ import {
parseWorkspacePageRange,
WorkspacePageSelectionError,
} from "#/features/workspaces/read-page-selection";
-import {
- decodeWorkspaceContentCursor,
- encodeWorkspaceContentCursor,
-} from "#/features/workspaces/content/workspace-content-cursor";
import {
createFlashcardRevision,
type Flashcard,
serializeFlashcardSetToHtml,
} from "#/features/workspaces/flashcards/flashcard-content";
-import type { WorkspaceLocation } from "#/features/workspaces/locations/workspace-location";
+import {
+ parseWorkspaceAddress,
+ resolveWorkspaceAddressLocation,
+} from "#/features/workspaces/locations/workspace-location";
import {
summarizeFlashcardStudyProgress,
type FlashcardStudyState,
} from "#/features/workspaces/flashcards/flashcard-study-state";
-import { sha256Base64UrlText } from "#/lib/binary";
+import {
+ createQuizQuestionRevision,
+ serializeQuizSetToHtml,
+ type QuizQuestion,
+} from "#/features/workspaces/quizzes/quiz-content";
+import {
+ getQuizAnswer,
+ summarizeQuizStudyProgress,
+ type QuizStudyState,
+} from "#/features/workspaces/quizzes/quiz-study-state";
-const maxWorkspaceContentBatchBytes = 2 * 1024 * 1024 + 64 * 1024;
-const targetFlashcardChunkCharacters = 48_000;
+// A context-sized ceiling for one whole read call, not a transport limit: once
+// a call has returned this much content, further requests in it fail fast and
+// say to read fewer units at a time.
+const maxWorkspaceReadCharacters = 200_000;
+const targetEntryChunkCharacters = 48_000;
interface DocumentContentReader {
readHtmlChunk(input: DocumentHtmlChunkReadInput): Promise;
@@ -61,6 +68,12 @@ type FlashcardItemReader = (
| { cards: Flashcard[]; studyState: FlashcardStudyState }
| Promise<{ cards: Flashcard[]; studyState: FlashcardStudyState }>;
+type QuizItemReader = (
+ itemId: string,
+) =>
+ | { questions: QuizQuestion[]; studyState: QuizStudyState }
+ | Promise<{ questions: QuizQuestion[]; studyState: QuizStudyState }>;
+
interface PendingReadyResult {
item: WorkspaceItem;
read: Extract;
@@ -71,90 +84,71 @@ export async function readWorkspaceContent(input: {
bucket: R2Bucket;
getDocumentSession: (itemId: string) => DocumentContentReader | Promise;
readFlashcardItem: FlashcardItemReader;
- resolveReference?: (itemId: string, ref: string) => WorkspaceLocation | undefined;
+ readQuizItem: QuizItemReader;
+ /** Resolves an item address's refKey to a live item and its path. */
+ resolveRefKey: (refKey: string) => Promise<{ item: WorkspaceItem; path: string } | undefined>;
requests: WorkspaceContentReadRequest[];
workspaceId: string;
}): Promise {
const { requests } = input;
- const encoder = new TextEncoder();
- const resolutions = await resolveWorkspacePaths({
- paths: requests.map((request) => request.path),
+ const pathResolutions = await resolveWorkspacePaths({
+ paths: requests.flatMap((request) => ("path" in request ? [request.path] : [])),
workspaceId: input.workspaceId,
});
const results: WorkspaceContentReadResult[] = [];
const readyResults: PendingReadyResult[] = [];
- let returnedContentBytes = 0;
- let readBudgetExhausted = false;
-
- // Reads stay ordered so each body is consumed before the shared byte budget advances.
- for (const [index, resolution] of resolutions.entries()) {
- const request = requests[index];
- if (!request) {
- throw new Error("Workspace content resolution did not match its request.");
- }
- if (resolution.status === "invalid_path") {
- results.push({ code: resolution.code, path: resolution.path, status: "failed" });
- continue;
- }
- if (resolution.status === "root") {
- results.push({ code: "path_is_folder", path: resolution.path, status: "failed" });
- continue;
- }
- if (resolution.status === "not_found") {
- results.push({ code: "path_not_found", path: resolution.path, status: "failed" });
- continue;
- }
- if (isWorkspaceItemContainer(resolution.item.type)) {
- results.push({ code: "path_is_folder", path: resolution.path, status: "failed" });
+ let returnedCharacters = 0;
+ let pathIndex = 0;
+
+ // Reads stay ordered so each body is consumed before the shared budget advances.
+ for (const request of requests) {
+ const resolved =
+ "path" in request
+ ? resolvePathRequest(pathResolutions[pathIndex++], request.path)
+ : await resolveRefRequest(input.resolveRefKey, request.ref);
+ if ("failure" in resolved) {
+ results.push(resolved.failure);
continue;
}
- const readBudgetFailure = {
- code: "read_budget_exceeded" as const,
- path: resolution.path,
- status: "failed" as const,
- ...(getWorkspaceItemContentKind(resolution.item.type) === "file"
- ? { type: "file" as const }
- : {}),
- };
- if (readBudgetExhausted) {
- results.push(readBudgetFailure);
+
+ if (returnedCharacters >= maxWorkspaceReadCharacters) {
+ results.push({
+ code: "read_budget_exceeded",
+ message: "This call already returned as much as fits. Read fewer units per call.",
+ path: resolved.path,
+ status: "failed",
+ });
continue;
}
try {
const read = await readWorkspaceItem({
...input,
- item: resolution.item,
+ item: resolved.item,
request,
- path: resolution.path,
+ path: resolved.path,
});
if (read.status !== "ready") {
results.push(read);
continue;
}
- const contentBytes = encoder.encode(
- "content" in read ? read.content : JSON.stringify(read.cards),
- ).byteLength;
- if (returnedContentBytes + contentBytes > maxWorkspaceContentBatchBytes) {
- readBudgetExhausted = true;
- results.push(readBudgetFailure);
- continue;
- }
- returnedContentBytes += contentBytes;
+ returnedCharacters +=
+ "content" in read
+ ? read.content.length
+ : JSON.stringify("cards" in read ? read.cards : read.questions).length;
- const pending = {
- item: resolution.item,
+ readyResults.push({
+ item: resolved.item,
read,
relations: listWorkspaceItemRelations({
- itemId: resolution.item.id,
+ itemId: resolved.item.id,
workspaceId: input.workspaceId,
}),
- };
- readyResults.push(pending);
+ });
results.push(read);
} catch (error) {
if (error instanceof WorkspacePageSelectionError) {
- results.push({ code: error.code, path: resolution.path, status: "failed" });
+ results.push({ code: error.code, path: resolved.path, status: "failed" });
continue;
}
throw error;
@@ -165,18 +159,52 @@ export async function readWorkspaceContent(input: {
return results;
}
+function resolvePathRequest(
+ resolution: Awaited>[number] | undefined,
+ path: string,
+): { item: WorkspaceItem; path: string } | { failure: WorkspaceContentReadResult } {
+ if (!resolution) {
+ throw new Error("Workspace content resolution did not match its request.");
+ }
+ if (resolution.status === "invalid_path") {
+ return { failure: { code: resolution.code, path: resolution.path, status: "failed" } };
+ }
+ if (resolution.status === "root") {
+ return { failure: { code: "path_is_folder", path: resolution.path, status: "failed" } };
+ }
+ if (resolution.status === "not_found") {
+ return { failure: { code: "path_not_found", path: resolution.path, status: "failed" } };
+ }
+ if (isWorkspaceItemContainer(resolution.item.type)) {
+ return { failure: { code: "path_is_folder", path, status: "failed" } };
+ }
+ return { item: resolution.item, path: resolution.path };
+}
+
+async function resolveRefRequest(
+ resolveRefKey: (refKey: string) => Promise<{ item: WorkspaceItem; path: string } | undefined>,
+ ref: string,
+): Promise<{ item: WorkspaceItem; path: string } | { failure: WorkspaceContentReadResult }> {
+ const address = parseWorkspaceAddress(ref);
+ const resolved = address ? await resolveRefKey(address.refKey) : undefined;
+ if (!resolved || isWorkspaceItemContainer(resolved.item.type)) {
+ return { failure: { code: "ref_not_found", ref, status: "failed" } };
+ }
+ return resolved;
+}
+
async function readWorkspaceItem(input: {
bucket: R2Bucket;
getDocumentSession: (itemId: string) => DocumentContentReader | Promise;
readFlashcardItem: FlashcardItemReader;
- resolveReference?: (itemId: string, ref: string) => WorkspaceLocation | undefined;
+ readQuizItem: QuizItemReader;
item: WorkspaceItem;
path: string;
request: WorkspaceContentReadRequest;
workspaceId: string;
}): Promise {
if (input.request.mode === "ref") {
- return readWorkspaceReference(input, input.request.ref);
+ return readWorkspaceUnit(input, input.request.ref);
}
switch (input.item.type) {
case "document":
@@ -187,36 +215,36 @@ async function readWorkspaceItem(input: {
return { code: "unsupported_item_type", path: input.path, status: "failed" };
case "flashcard":
return readFlashcards(input);
+ case "quiz":
+ return readQuiz(input);
}
}
-async function readWorkspaceReference(
+/** Reads the exact content an address identifies: one page, block, or entry. */
+async function readWorkspaceUnit(
input: Parameters[0],
ref: string,
): Promise {
- const location = input.resolveReference?.(input.item.id, ref);
- if (!location || location.itemId !== input.item.id) {
- return { code: "ref_not_found", path: input.path, status: "failed" };
+ const address = parseWorkspaceAddress(ref);
+ const location = address ? resolveWorkspaceAddressLocation(input.item, address) : undefined;
+ if (!location) {
+ return { code: "ref_not_found", ref, status: "failed" };
}
switch (location.kind) {
case "item":
return readWorkspaceItem({ ...input, request: { mode: "start", path: input.path } });
case "pdf-page":
- return input.item.type === "file"
- ? readFile({
- ...input,
- request: { mode: "pages", path: input.path, range: String(location.pageNumber) },
- })
- : { code: "ref_not_found", path: input.path, status: "failed" };
+ return readFile({
+ ...input,
+ request: { mode: "pages", path: input.path, range: String(location.pageNumber) },
+ });
case "document-block":
- return input.item.type === "document"
- ? readDocumentBlock(input, location.blockId)
- : { code: "ref_not_found", path: input.path, status: "failed" };
+ return readDocumentBlock(input, location.blockId);
case "flashcard":
- return input.item.type === "flashcard"
- ? readFlashcards(input, location.cardId)
- : { code: "ref_not_found", path: input.path, status: "failed" };
+ return readFlashcards(input, location.cardId);
+ case "quiz-question":
+ return readQuiz(input, location.questionId);
}
}
@@ -230,73 +258,23 @@ async function readFlashcards(
},
targetCardId?: string,
): Promise {
- if (
- !targetCardId &&
- input.request.mode !== "start" &&
- input.request.mode !== "continue" &&
- input.request.mode !== "cards"
- ) {
- return { code: "invalid_selection", path: input.path, status: "failed" };
- }
-
const { cards, studyState } = await input.readFlashcardItem(input.item.id);
const cardsById = new Map(cards.map((card) => [card.id, card]));
- const serializedCards = serializeFlashcardSetToHtml({ cards, version: 1 });
- let selectedCards: typeof serializedCards;
- let returned: number[];
- let nextCursor: string | undefined;
-
- if (targetCardId) {
- const cardIndex = serializedCards.findIndex((card) => card.id === targetCardId);
- if (cardIndex < 0) return { code: "ref_not_found", path: input.path, status: "failed" };
- selectedCards = [serializedCards[cardIndex]!];
- returned = [cardIndex + 1];
- } else if (input.request.mode === "cards") {
- try {
- returned = parseWorkspacePageRange(input.request.range, cards.length);
- } catch (error) {
- if (error instanceof WorkspacePageSelectionError) {
- return { code: "invalid_selection", path: input.path, status: "failed" };
- }
- throw error;
- }
- selectedCards = returned.map((cardNumber) => serializedCards[cardNumber - 1]!);
- } else {
- const encodedCursor = input.request.mode === "continue" ? input.request.cursor : undefined;
- const cursor = encodedCursor ? decodeWorkspaceContentCursor(encodedCursor) : undefined;
- if (encodedCursor && (!cursor || cursor.kind !== "flashcard" || cursor.path !== input.path)) {
- return { code: "invalid_cursor", path: input.path, status: "failed" };
- }
-
- const revision = await sha256Base64UrlText(JSON.stringify(cards));
- if (cursor?.kind === "flashcard" && cursor.revision !== revision) {
- return { code: "content_changed", path: input.path, status: "failed" };
- }
-
- const offset = cursor?.kind === "flashcard" ? cursor.offset : 0;
- const chunk = readFlashcardChunk(serializedCards, offset);
- if (!chunk) return { code: "invalid_cursor", path: input.path, status: "failed" };
- selectedCards = chunk.cards;
- returned = Array.from({ length: chunk.endOffset - offset }, (_, index) => offset + index + 1);
- if (chunk.endOffset < cards.length) {
- nextCursor = encodeWorkspaceContentCursor({
- kind: "flashcard",
- offset: chunk.endOffset,
- path: input.path,
- revision,
- version: 1,
- });
- }
- }
+ const selection = selectOrderedEntries({
+ entries: serializeFlashcardSetToHtml({ cards, version: 1 }),
+ measure: (card) => card.front.length + card.back.length,
+ request: input.request,
+ targetEntryId: targetCardId,
+ });
+ if (!selection.ok) return { code: selection.code, path: input.path, status: "failed" };
return {
cards: await Promise.all(
- selectedCards.map(async (card) => {
+ selection.selected.map(async (card) => {
const source = cardsById.get(card.id);
if (!source) throw new Error("Serialized flashcard does not match its source set.");
return {
- cardId: card.id,
- revision: await createFlashcardRevision(source),
+ ref: `${card.id}.r_${await createFlashcardRevision(source)}`,
front: card.front,
back: card.back,
...(studyState.cards[card.id] ? { study: studyState.cards[card.id] } : {}),
@@ -306,35 +284,141 @@ async function readFlashcards(
format: "html",
itemId: input.item.id,
location: {
- kind: "cards",
- returned,
+ kind: "entries",
+ returned: selection.returned,
total: cards.length,
},
- ...(nextCursor ? { nextCursor } : {}),
path: input.path,
progress: summarizeFlashcardStudyProgress(
cards.map((card) => card.id),
studyState,
),
+ ref: input.item.refKey,
status: "ready",
type: "flashcard",
};
}
-function readFlashcardChunk(cards: ReturnType, offset: number) {
- if (offset < 0 || offset >= cards.length) return null;
+async function readQuiz(
+ input: {
+ item: WorkspaceItem;
+ path: string;
+ readQuizItem: QuizItemReader;
+ request: WorkspaceContentReadRequest;
+ workspaceId: string;
+ },
+ targetQuestionId?: string,
+): Promise {
+ const { questions, studyState } = await input.readQuizItem(input.item.id);
+ const questionsById = new Map(questions.map((question) => [question.id, question]));
+ const selection = selectOrderedEntries({
+ entries: serializeQuizSetToHtml({ questions, version: 1 }),
+ measure: (question) =>
+ question.question.length +
+ question.explanation.length +
+ question.options.reduce((total, option) => total + option.text.length, 0),
+ request: input.request,
+ targetEntryId: targetQuestionId,
+ });
+ if (!selection.ok) return { code: selection.code, path: input.path, status: "failed" };
+
+ return {
+ format: "html",
+ itemId: input.item.id,
+ location: {
+ kind: "entries",
+ returned: selection.returned,
+ total: questions.length,
+ },
+ path: input.path,
+ progress: summarizeQuizStudyProgress(questions, studyState),
+ questions: await Promise.all(
+ selection.selected.map(async (question) => {
+ const source = questionsById.get(question.id);
+ if (!source) throw new Error("Serialized quiz question does not match its source set.");
+ const answer = getQuizAnswer(source, studyState);
+ const selectedIndex = answer
+ ? source.options.findIndex((option) => option.id === answer.selectedOptionId)
+ : -1;
+ return {
+ ref: `${question.id}.r_${await createQuizQuestionRevision(source)}`,
+ question: question.question,
+ options: question.options.map(({ text, correct }) => ({ text, correct })),
+ explanation: question.explanation,
+ ...(answer && selectedIndex >= 0
+ ? {
+ answer: {
+ selected: selectedIndex + 1,
+ correct: answer.selectedOptionId === source.correctOptionId,
+ },
+ }
+ : {}),
+ };
+ }),
+ ),
+ ref: input.item.refKey,
+ status: "ready",
+ type: "quiz",
+ };
+}
+
+type OrderedEntrySelection =
+ | { ok: true; selected: T[]; returned: number[] }
+ | { ok: false; code: "invalid_selection" | "ref_not_found" };
+
+/**
+ * Shared selection for structured items: one targeted entry from an address,
+ * an explicit entry range, or the first character-budgeted chunk on `start`.
+ * Every result names the entry numbers it covered, so continuing is just the
+ * next range — no cursor to carry.
+ */
+function selectOrderedEntries(input: {
+ entries: T[];
+ measure: (entry: T) => number;
+ request: WorkspaceContentReadRequest;
+ targetEntryId?: string;
+}): OrderedEntrySelection {
+ const { entries, request, targetEntryId } = input;
+
+ if (targetEntryId) {
+ const entryIndex = entries.findIndex((entry) => entry.id === targetEntryId);
+ if (entryIndex < 0) return { ok: false, code: "ref_not_found" };
+ return { ok: true, selected: [entries[entryIndex]!], returned: [entryIndex + 1] };
+ }
+ if (request.mode === "entries") {
+ let returned: number[];
+ try {
+ returned = parseWorkspacePageRange(request.range, entries.length);
+ } catch (error) {
+ if (error instanceof WorkspacePageSelectionError) {
+ return { ok: false, code: "invalid_selection" };
+ }
+ throw error;
+ }
+ return {
+ ok: true,
+ selected: returned.map((entryNumber) => entries[entryNumber - 1]!),
+ returned,
+ };
+ }
+ if (request.mode !== "start") {
+ return { ok: false, code: "invalid_selection" };
+ }
let characters = 0;
- let endOffset = offset;
- while (endOffset < cards.length) {
- const card = cards[endOffset]!;
- const cardCharacters = card.front.length + card.back.length;
- if (endOffset > offset && characters + cardCharacters > targetFlashcardChunkCharacters) break;
- characters += cardCharacters;
+ let endOffset = 0;
+ while (endOffset < entries.length) {
+ const entryCharacters = input.measure(entries[endOffset]!);
+ if (endOffset > 0 && characters + entryCharacters > targetEntryChunkCharacters) break;
+ characters += entryCharacters;
endOffset += 1;
}
- return { cards: cards.slice(offset, endOffset), endOffset };
+ return {
+ ok: true,
+ selected: entries.slice(0, endOffset),
+ returned: Array.from({ length: endOffset }, (_, index) => index + 1),
+ };
}
/**
@@ -364,6 +448,7 @@ async function readDocumentBlock(
format: "html",
itemId: input.item.id,
path: input.path,
+ ref: input.item.refKey,
status: "ready",
type: "block",
};
@@ -376,26 +461,31 @@ async function readDocument(input: {
request: WorkspaceContentReadRequest;
workspaceId: string;
}): Promise {
- if (input.request.mode !== "start" && input.request.mode !== "continue") {
+ let chunkInput: DocumentHtmlChunkReadInput;
+ if (input.request.mode === "start") {
+ chunkInput = { offset: 0 };
+ } else if (input.request.mode === "entries") {
+ // Blocks are contiguous prose; a scattered range has no meaningful join.
+ const range = /^(\d+)(?:\s*-\s*(\d+))?$/.exec(input.request.range);
+ const startBlock = range ? Number(range[1]) : 0;
+ const endBlock = range?.[2] ? Number(range[2]) : startBlock;
+ if (!range || startBlock < 1 || endBlock < startBlock) {
+ return {
+ code: "invalid_selection",
+ message: "Document entries must be one block number or one contiguous range like 5-12.",
+ path: input.path,
+ status: "failed",
+ };
+ }
+ chunkInput = { offset: startBlock - 1, maxBlocks: endBlock - startBlock + 1 };
+ } else {
return { code: "invalid_selection", path: input.path, status: "failed" };
}
- const encodedCursor = input.request.mode === "continue" ? input.request.cursor : undefined;
- const cursor = encodedCursor ? decodeWorkspaceContentCursor(encodedCursor) : undefined;
- if (encodedCursor && (!cursor || cursor.kind !== "document" || cursor.path !== input.path)) {
- return { code: "invalid_cursor", path: input.path, status: "failed" };
- }
-
const documentSession = await input.getDocumentSession(input.item.id);
- const chunk = await documentSession.readHtmlChunk({
- expectedRevision: cursor?.kind === "document" ? cursor.revision : undefined,
- offset: cursor?.kind === "document" ? cursor.offset : 0,
- });
- if (chunk.status === "content_changed") {
- return { code: "content_changed", path: input.path, status: "failed" };
- }
+ const chunk = await documentSession.readHtmlChunk(chunkInput);
if (chunk.status === "invalid_offset") {
- return { code: "invalid_cursor", path: input.path, status: "failed" };
+ return { code: "invalid_selection", path: input.path, status: "failed" };
}
return {
@@ -403,18 +493,8 @@ async function readDocument(input: {
format: "html",
itemId: input.item.id,
location: { kind: "blocks", ...chunk.location },
- ...(chunk.nextOffset === undefined
- ? {}
- : {
- nextCursor: encodeWorkspaceContentCursor({
- kind: "document",
- offset: chunk.nextOffset,
- path: input.path,
- revision: chunk.revision,
- version: 3,
- }),
- }),
path: input.path,
+ ref: input.item.refKey,
status: "ready",
type: "document",
};
@@ -427,11 +507,7 @@ async function readFile(input: {
request: WorkspaceContentReadRequest;
workspaceId: string;
}): Promise {
- if (
- input.request.mode !== "start" &&
- input.request.mode !== "continue" &&
- input.request.mode !== "pages"
- ) {
+ if (input.request.mode !== "start" && input.request.mode !== "pages") {
return { code: "invalid_selection", path: input.path, status: "failed" };
}
const fileType = resolveWorkspaceFileTypeFromItem(input.item);
@@ -450,25 +526,12 @@ async function readFile(input: {
return describeUnreadableProjection(projection, input.path, input.item.id);
}
- const encodedCursor = input.request.mode === "continue" ? input.request.cursor : undefined;
- const cursor = encodedCursor ? decodeWorkspaceContentCursor(encodedCursor) : undefined;
- if (encodedCursor && (!cursor || cursor.kind !== "file" || cursor.path !== input.path)) {
- return { code: "invalid_cursor", path: input.path, status: "failed" };
- }
- if (cursor?.kind === "file" && cursor.sourceHash !== projection.sourceHash) {
- return { code: "content_changed", path: input.path, status: "failed" };
- }
let pageRead: Awaited>;
try {
pageRead = await readWorkspacePageProjection({
itemId: input.item.id,
pageCount: projection.pageCount,
- pages:
- cursor?.kind === "file"
- ? String(cursor.nextPage)
- : input.request.mode === "pages"
- ? input.request.range
- : undefined,
+ pages: input.request.mode === "pages" ? input.request.range : undefined,
workspaceId: input.workspaceId,
});
} catch (error) {
@@ -477,7 +540,6 @@ async function readFile(input: {
}
return { code: "projection_failed", path: input.path, status: "failed", type: "file" };
}
- const nextPage = Math.max(...pageRead.pages.returned) + 1;
return {
assetKind: fileType.assetKind,
content: pageRead.content,
@@ -485,19 +547,9 @@ async function readFile(input: {
format: "markdown",
itemId: input.item.id,
location: { kind: "pages", ...pageRead.pages },
- ...(nextPage > pageRead.pages.total
- ? {}
- : {
- nextCursor: encodeWorkspaceContentCursor({
- kind: "file",
- nextPage,
- path: input.path,
- sourceHash: projection.sourceHash,
- version: 2,
- }),
- }),
path: input.path,
...(projection.provisional ? { provisional: true } : {}),
+ ref: input.item.refKey,
status: "ready",
type: "file",
};
diff --git a/src/features/workspaces/content/workspace-read-model-output.test.ts b/src/features/workspaces/content/workspace-read-model-output.test.ts
new file mode 100644
index 00000000..47ffdbcd
--- /dev/null
+++ b/src/features/workspaces/content/workspace-read-model-output.test.ts
@@ -0,0 +1,83 @@
+import { describe, expect, it } from "vitest";
+
+import type { WorkspaceReadItemsOutput } from "#/features/workspaces/content/workspace-content-contract";
+import { createWorkspaceReadItemsModelOutput } from "#/features/workspaces/content/workspace-read-model-output";
+
+describe("workspace read model output", () => {
+ it("drops internal item ids and keeps self-describing refs", () => {
+ const output: WorkspaceReadItemsOutput = {
+ results: [
+ {
+ content: 'Notes
',
+ format: "html",
+ itemId: "document-1",
+ location: { endBlock: 1, kind: "blocks", startBlock: 1, totalBlocks: 1 },
+ path: "/Notes",
+ ref: "Xk7p2Qa9",
+ status: "ready",
+ type: "document",
+ },
+ ],
+ };
+
+ const modelOutput = createWorkspaceReadItemsModelOutput(output);
+ expect(modelOutput).not.toHaveProperty("guidance");
+ expect(modelOutput.results[0]).toMatchObject({
+ content: expect.stringContaining('data-ref="b_abcdefghijkl.r_012345"'),
+ path: "/Notes",
+ ref: "Xk7p2Qa9",
+ status: "ready",
+ });
+ expect(JSON.stringify(modelOutput)).not.toContain("document-1");
+ });
+
+ it("emits each handling guidance once per situation", () => {
+ const output: WorkspaceReadItemsOutput = {
+ results: [
+ {
+ elapsedSeconds: 5,
+ path: "/A.pdf",
+ phase: "extracting",
+ retryAfterSeconds: 10,
+ status: "pending",
+ type: "file",
+ },
+ {
+ elapsedSeconds: 9,
+ path: "/B.pdf",
+ phase: "queued",
+ retryAfterSeconds: 10,
+ status: "pending",
+ type: "file",
+ },
+ { code: "extraction_failed", path: "/C.pdf", status: "failed", type: "file" },
+ ],
+ };
+
+ const modelOutput = createWorkspaceReadItemsModelOutput(output);
+ expect(modelOutput.guidance).toHaveLength(2);
+ expect(modelOutput.guidance?.[0]).toContain("still extracting");
+ expect(modelOutput.guidance?.[1]).toContain("will not finish");
+ });
+
+ it("does not warn about empty pages once extraction is final", () => {
+ const output: WorkspaceReadItemsOutput = {
+ results: [
+ {
+ assetKind: "pdf",
+ content: "## Page 1",
+ emptyPages: [1],
+ format: "markdown",
+ itemId: "file-1",
+ location: { kind: "pages", requested: "1", returned: [1], total: 1 },
+ path: "/Book.pdf",
+ ref: "Yk7p2Qa9",
+ status: "ready",
+ type: "file",
+ },
+ ],
+ };
+
+ expect(createWorkspaceReadItemsModelOutput(output)).not.toHaveProperty("guidance");
+ });
+});
diff --git a/src/features/workspaces/content/workspace-read-model-output.ts b/src/features/workspaces/content/workspace-read-model-output.ts
new file mode 100644
index 00000000..9bf10023
--- /dev/null
+++ b/src/features/workspaces/content/workspace-read-model-output.ts
@@ -0,0 +1,81 @@
+import type {
+ WorkspaceContentReadResult,
+ WorkspaceReadItemsOutput,
+} from "#/features/workspaces/content/workspace-content-contract";
+
+/**
+ * Guidance for read outcomes the model has to react to, keyed by situation.
+ *
+ * These live here rather than in the tool description because none of them
+ * change how a read is issued, and background extraction states are rare enough
+ * that every request should not carry the instructions for handling them.
+ */
+const workspaceReadGuidance = {
+ pending:
+ "Some paths are still extracting. Never sleep, poll, or otherwise stall waiting for them, including inside compute, sandbox_bash, or orchestrate. If an original file is attached, use it and do not read that path again in this reply. Otherwise, either do other work and read pending paths again later in this reply, or tell the user they are still processing and to ask again in about retryAfterSeconds. Never read the same pending path more than twice in one reply.",
+ unrecoverable:
+ "Extraction will not finish for some paths. Report the code and any message to the user; do not retry those reads and do not suggest re-uploading the file.",
+ transient:
+ "Some paths failed on a transient storage problem. One repeat read is reasonable; if it fails again, tell the user.",
+ provisional:
+ "Some content came from a fast first pass. Pages listed in emptyPages are still extracting, so read them again later rather than reporting them as blank.",
+} as const;
+
+/**
+ * Collects the handling guidance a set of read results calls for.
+ *
+ * Emitted once per situation rather than once per result so a batch of pending
+ * reads does not repeat the same paragraph for every path.
+ */
+function createWorkspaceReadGuidance(results: readonly WorkspaceContentReadResult[]): string[] {
+ const situations = new Set();
+
+ for (const result of results) {
+ if (result.status === "pending") {
+ situations.add("pending");
+ continue;
+ }
+
+ if (result.status === "failed") {
+ if (result.code === "extraction_failed" || result.code === "extraction_stalled") {
+ situations.add("unrecoverable");
+ } else if (result.code === "projection_failed") {
+ situations.add("transient");
+ }
+ continue;
+ }
+
+ // Gate on provisional only: emptyPages on a final (non-provisional) read
+ // describes genuinely blank pages, which must not be reported as still
+ // extracting or the model retries a completed read forever.
+ if (result.type === "file" && result.provisional) {
+ situations.add("provisional");
+ }
+ }
+
+ return (Object.keys(workspaceReadGuidance) as Array)
+ .filter((situation) => situations.has(situation))
+ .map((situation) => workspaceReadGuidance[situation]);
+}
+
+/**
+ * Projects a rich workspace read result into the model-visible JSON.
+ *
+ * The results already carry self-describing addresses, so the only work left
+ * is dropping the internal item id and attaching guidance for outcomes that
+ * need handling.
+ */
+export function createWorkspaceReadItemsModelOutput(output: WorkspaceReadItemsOutput) {
+ const guidance = createWorkspaceReadGuidance(output.results);
+
+ return {
+ ...(guidance.length > 0 ? { guidance } : {}),
+ results: output.results.map(omitWorkspaceReadItemId),
+ };
+}
+
+function omitWorkspaceReadItemId(result: T): Omit {
+ const { itemId: _itemId, ...modelResult } = result as T & { itemId?: string };
+
+ return modelResult;
+}
diff --git a/src/features/workspaces/content/workspace-read-references.test.ts b/src/features/workspaces/content/workspace-read-references.test.ts
deleted file mode 100644
index 4fca8c2d..00000000
--- a/src/features/workspaces/content/workspace-read-references.test.ts
+++ /dev/null
@@ -1,274 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import type {
- WorkspaceContentReadResult,
- WorkspaceReadItemsOutput,
-} from "#/features/workspaces/content/workspace-content-contract";
-import {
- createWorkspaceReadItemsModelOutput,
- createWorkspaceReadReferences,
-} from "#/features/workspaces/content/workspace-read-references";
-
-describe("workspace read references", () => {
- it("gives document blocks and extracted pages one transcript-backed ref each", () => {
- const results = [documentResult(), fileResult()] satisfies WorkspaceContentReadResult[];
- const references = createWorkspaceReadReferences(results);
-
- expect(references).toHaveLength(3);
- expect(references.map(({ location }) => location)).toEqual([
- {
- blockId: "b_abcdefghijkl",
- itemId: "document-1",
- kind: "document-block",
- version: 1,
- },
- { itemId: "file-1", kind: "pdf-page", pageNumber: 12, version: 1 },
- { itemId: "file-1", kind: "pdf-page", pageNumber: 13, version: 1 },
- ]);
- expect(references.every(({ ref }) => /^wr_[0-9A-Za-z]{8}$/.test(ref))).toBe(true);
- });
-
- it("projects refs beside content without exposing durable item IDs", () => {
- const results = [documentResult(), fileResult()] satisfies WorkspaceContentReadResult[];
- const output: WorkspaceReadItemsOutput = {
- references: createWorkspaceReadReferences(results),
- results,
- };
- const modelOutput = createWorkspaceReadItemsModelOutput(output);
- const document = modelOutput.results[0];
- const file = modelOutput.results[1];
-
- expect(document).toMatchObject({
- content: expect.stringMatching(/data-ref="wr_[0-9A-Za-z]{8}"/),
- path: "/Notes",
- status: "ready",
- type: "document",
- });
- expect(file).toMatchObject({
- status: "ready",
- type: "file",
- });
- expect(file).not.toHaveProperty("pageReferences");
- expect(file && "content" in file ? file.content : "").toMatch(
- /^## Page 12 \[ref: wr_[0-9A-Za-z]{8}\]$/m,
- );
- expect(file && "content" in file ? file.content : "").toMatch(
- /^## Page 13 \[ref: wr_[0-9A-Za-z]{8}\]$/m,
- );
- expect(JSON.stringify(modelOutput)).not.toContain("document-1");
- expect(JSON.stringify(modelOutput)).not.toContain("file-1");
- });
-
- it("gives each flashcard one ref for editing, citation, and navigation", () => {
- const results = [flashcardResult()] satisfies WorkspaceContentReadResult[];
- const references = createWorkspaceReadReferences(results);
- const modelOutput = createWorkspaceReadItemsModelOutput({ references, results });
-
- expect(references.map(({ location }) => location)).toEqual([
- {
- cardId: "f67080f9-0158-4565-86a9-4c90ed6809d2",
- itemId: "flashcard-1",
- kind: "flashcard",
- version: 1,
- },
- ]);
- expect(modelOutput.results[0]).toMatchObject({
- cards: [
- {
- back: "Paris
",
- front: "Capital of France?
",
- ref: expect.stringMatching(/^wr_[0-9A-Za-z]{8}$/),
- },
- ],
- path: "/Geography",
- progress: { gotItCount: 1, missedCount: 0, reviewedCount: 1 },
- type: "flashcard",
- });
- expect(JSON.stringify(modelOutput)).not.toContain("flashcard-1");
- });
-
- it("deduplicates repeated reads of the same durable location in one result", () => {
- const references = createWorkspaceReadReferences([
- documentResult(),
- { ...documentResult(), content: "continued" },
- ]);
-
- expect(references).toHaveLength(1);
- });
-
- it("uses an item ref for extracted images that have no page-navigation surface", () => {
- const image = {
- ...fileResult(),
- assetKind: "image",
- itemId: "image-1",
- path: "/Diagram.png",
- } satisfies Extract;
- const references = createWorkspaceReadReferences([image]);
- const modelOutput = createWorkspaceReadItemsModelOutput({
- references,
- results: [image],
- });
-
- expect(references).toMatchObject([
- { location: { itemId: "image-1", kind: "item", version: 1 } },
- ]);
- expect(modelOutput.results[0]).toMatchObject({
- assetKind: "image",
- ref: expect.stringMatching(/^wr_[0-9A-Za-z]{8}$/),
- });
- expect(modelOutput.results[0]).not.toHaveProperty("pageReferences");
- });
-
- it("stays silent when every read succeeded outright", () => {
- const results = [documentResult(), fileResult()] satisfies WorkspaceContentReadResult[];
-
- expect(
- createWorkspaceReadItemsModelOutput({
- references: createWorkspaceReadReferences(results),
- results,
- }),
- ).not.toHaveProperty("guidance");
- });
-
- it("explains a pending read once however many paths are waiting", () => {
- const results = [
- {
- elapsedSeconds: 4,
- itemId: "file-a",
- path: "/A.pdf",
- phase: "extracting",
- retryAfterSeconds: 15,
- status: "pending",
- type: "file",
- },
- {
- elapsedSeconds: 0,
- path: "/B.pdf",
- phase: "queued",
- retryAfterSeconds: 15,
- status: "pending",
- type: "file",
- },
- ] satisfies WorkspaceContentReadResult[];
- const modelOutput = createWorkspaceReadItemsModelOutput({ references: [], results });
- const { guidance } = modelOutput;
-
- expect(guidance).toHaveLength(1);
- expect(guidance?.[0]).toContain("Never sleep");
- expect(JSON.stringify(modelOutput)).not.toContain("file-a");
- });
-
- it("separates failures that will never resolve from transient ones", () => {
- const results = [
- { code: "extraction_failed", path: "/A.pdf", status: "failed", type: "file" },
- { code: "extraction_stalled", path: "/B.pdf", status: "failed", type: "file" },
- { code: "projection_failed", path: "/C.pdf", status: "failed", type: "file" },
- ] satisfies WorkspaceContentReadResult[];
- const guidance = createWorkspaceReadItemsModelOutput({ references: [], results }).guidance;
-
- expect(guidance).toHaveLength(2);
- expect(guidance?.[0]).toContain("do not suggest re-uploading");
- expect(guidance?.[1]).toContain("One repeat read is reasonable");
- });
-
- it("says nothing about failures that are the caller's own mistake", () => {
- const results = [
- { code: "path_not_found", path: "/Missing.pdf", status: "failed" },
- ] satisfies WorkspaceContentReadResult[];
-
- expect(createWorkspaceReadItemsModelOutput({ references: [], results })).not.toHaveProperty(
- "guidance",
- );
- });
-
- it("warns that blank pages from the fast pass are not final", () => {
- const results = [
- { ...fileResult(), emptyPages: [13], provisional: true },
- ] satisfies WorkspaceContentReadResult[];
- const guidance = createWorkspaceReadItemsModelOutput({
- references: createWorkspaceReadReferences(results),
- results,
- }).guidance;
-
- expect(guidance).toHaveLength(1);
- expect(guidance?.[0]).toContain("still extracting");
- });
-
- it("stays silent about blank pages on a final, non-provisional read", () => {
- const results = [{ ...fileResult(), emptyPages: [13] }] satisfies WorkspaceContentReadResult[];
-
- expect(
- createWorkspaceReadItemsModelOutput({
- references: createWorkspaceReadReferences(results),
- results,
- }),
- ).not.toHaveProperty("guidance");
- });
-});
-
-function documentResult(): Extract<
- WorkspaceContentReadResult,
- { status: "ready"; type: "document" }
-> {
- return {
- content: 'Notes
',
- format: "html",
- itemId: "document-1",
- location: { endBlock: 1, kind: "blocks", startBlock: 1, totalBlocks: 1 },
- path: "/Notes",
- status: "ready",
- type: "document",
- };
-}
-
-function fileResult(): Extract {
- return {
- assetKind: "pdf",
- content: "## Page 12\n\nAlpha\n\n## Page 13\n\nBeta",
- format: "markdown",
- itemId: "file-1",
- location: {
- kind: "pages",
- requested: "12-13",
- returned: [12, 13],
- total: 20,
- },
- path: "/Book.pdf",
- status: "ready",
- type: "file",
- };
-}
-
-function flashcardResult(): Extract<
- WorkspaceContentReadResult,
- { status: "ready"; type: "flashcard" }
-> {
- return {
- cards: [
- {
- back: "Paris
",
- cardId: "f67080f9-0158-4565-86a9-4c90ed6809d2",
- revision: "0123456789",
- front: "Capital of France?
",
- study: {
- lastRating: "good",
- lastReviewedAt: "2026-08-13T12:00:00.000Z",
- reviewCount: 1,
- },
- },
- ],
- format: "html",
- itemId: "flashcard-1",
- location: { kind: "cards", returned: [1], total: 1 },
- path: "/Geography",
- progress: {
- gotItCount: 1,
- missedCount: 0,
- reviewedCount: 1,
- totalCards: 1,
- unreviewedCount: 0,
- },
- status: "ready",
- type: "flashcard",
- };
-}
diff --git a/src/features/workspaces/content/workspace-read-references.ts b/src/features/workspaces/content/workspace-read-references.ts
deleted file mode 100644
index 29cf6ad9..00000000
--- a/src/features/workspaces/content/workspace-read-references.ts
+++ /dev/null
@@ -1,268 +0,0 @@
-import {
- createWorkspaceReferenceRecords,
- getWorkspaceLocationKey,
- type WorkspaceLocation,
- type WorkspaceReference,
- type WorkspaceReferenceRecord,
-} from "#/features/workspaces/locations/workspace-location";
-import {
- parseDocumentAiRef,
- readDocumentAiRefs,
- readDocumentAiRefRevision,
-} from "#/features/workspaces/documents/document-ai-html";
-import type {
- WorkspaceContentReadResult,
- WorkspaceReadItemsOutput,
-} from "#/features/workspaces/content/workspace-content-contract";
-
-/**
- * Allocates durable-location records for every ready workspace read.
- *
- * Editable blocks and cards retain a revision with their durable location.
- * PDFs receive one location per physical page; other files use the item.
- *
- * @param results - Ordered workspace read results.
- * @returns Deduplicated reference records for the rich tool result.
- */
-export function createWorkspaceReadReferences(
- results: readonly WorkspaceContentReadResult[],
-): WorkspaceReferenceRecord[] {
- const targets: Array = [];
-
- for (const result of results) {
- if (result.status !== "ready") {
- continue;
- }
- if (result.type === "flashcard") {
- for (const card of result.cards) {
- targets.push({
- location: {
- itemId: result.itemId,
- kind: "flashcard",
- cardId: card.cardId,
- version: 1,
- },
- revision: card.revision,
- });
- }
- continue;
- }
- if (result.type === "document" || result.type === "block") {
- const contentRefs =
- result.type === "block" ? [result.contentRef] : readDocumentAiRefs(result.content);
- for (const contentRef of contentRefs) {
- const blockId = parseDocumentAiRef(contentRef);
- const revision = readDocumentAiRefRevision(contentRef);
- if (!blockId || !revision)
- throw new Error("Document read returned an invalid content ref.");
- targets.push({
- location: { blockId, itemId: result.itemId, kind: "document-block", version: 1 },
- revision,
- });
- }
- continue;
- }
-
- if (result.type !== "file" || result.assetKind !== "pdf") {
- targets.push({
- itemId: result.itemId,
- kind: "item",
- version: 1,
- });
- continue;
- }
-
- for (const pageNumber of result.location.returned) {
- targets.push({
- itemId: result.itemId,
- kind: "pdf-page",
- pageNumber,
- version: 1,
- });
- }
- }
-
- return createWorkspaceReferenceRecords(targets);
-}
-
-/**
- * Guidance for read outcomes the model has to react to, keyed by situation.
- *
- * These live here rather than in the tool description because none of them
- * change how a read is issued, and background extraction states are rare enough
- * that every request should not carry the instructions for handling them.
- */
-const workspaceReadGuidance = {
- pending:
- "Some paths are still extracting. Never sleep, poll, or otherwise stall waiting for them, including inside compute, sandbox_bash, or orchestrate. If an original file is attached, use it and do not read that path again in this reply. Otherwise, either do other work and read pending paths again later in this reply, or tell the user they are still processing and to ask again in about retryAfterSeconds. Never read the same pending path more than twice in one reply.",
- unrecoverable:
- "Extraction will not finish for some paths. Report the code and any message to the user; do not retry those reads and do not suggest re-uploading the file.",
- transient:
- "Some paths failed on a transient storage problem. One repeat read is reasonable; if it fails again, tell the user.",
- provisional:
- "Some content came from a fast first pass. Pages listed in emptyPages are still extracting, so read them again later rather than reporting them as blank.",
-} as const;
-
-/**
- * Collects the handling guidance a set of read results calls for.
- *
- * Emitted once per situation rather than once per result so a batch of pending
- * reads does not repeat the same paragraph for every path.
- *
- * @param results - Ordered workspace read results.
- * @returns Guidance lines for the situations present, most actionable first.
- */
-function createWorkspaceReadGuidance(results: readonly WorkspaceContentReadResult[]): string[] {
- const situations = new Set();
-
- for (const result of results) {
- if (result.status === "pending") {
- situations.add("pending");
- continue;
- }
-
- if (result.status === "failed") {
- if (result.code === "extraction_failed" || result.code === "extraction_stalled") {
- situations.add("unrecoverable");
- } else if (result.code === "projection_failed") {
- situations.add("transient");
- }
- continue;
- }
-
- // Gate on provisional only: emptyPages on a final (non-provisional) read
- // describes genuinely blank pages, which must not be reported as still
- // extracting or the model retries a completed read forever.
- if (result.type === "file" && result.provisional) {
- situations.add("provisional");
- }
- }
-
- return (Object.keys(workspaceReadGuidance) as Array)
- .filter((situation) => situations.has(situation))
- .map((situation) => workspaceReadGuidance[situation]);
-}
-
-/**
- * Projects a rich workspace read result into compact model-visible JSON.
- *
- * Raw item IDs and durable locations remain in the persisted tool result.
- * Model-visible content receives only opaque refs next to the content they
- * identify, plus guidance for any outcome that needs handling.
- *
- * @param output - Validated rich workspace read output.
- * @returns JSON-safe results annotated with short workspace refs.
- */
-export function createWorkspaceReadItemsModelOutput(output: WorkspaceReadItemsOutput) {
- const refsByLocation = new Map(
- output.references.map((record) => [getWorkspaceLocationKey(record.location), record.ref]),
- );
- const refFor = (location: WorkspaceLocation) =>
- refsByLocation.get(getWorkspaceLocationKey(location));
- const guidance = createWorkspaceReadGuidance(output.results);
-
- return {
- ...(guidance.length > 0 ? { guidance } : {}),
- results: output.results.map((result) => {
- if (result.status === "pending") {
- return omitWorkspaceReadItemId(result);
- }
-
- if (result.status === "failed") {
- return result;
- }
- if (result.type === "flashcard") {
- return {
- ...omitWorkspaceReadItemId(result),
- cards: result.cards.map(({ cardId, revision: _revision, ...card }) => ({
- ...card,
- ref: refFor({ itemId: result.itemId, kind: "flashcard", cardId, version: 1 }),
- })),
- };
- }
- if (result.type === "document") {
- return {
- ...omitWorkspaceReadItemId(result),
- content: replaceDocumentContentRefs(result, refsByLocation),
- };
- }
- if (result.type === "block") {
- const blockId = parseDocumentAiRef(result.contentRef);
- const ref = blockId
- ? refFor({ blockId, itemId: result.itemId, kind: "document-block", version: 1 })
- : undefined;
- const { contentRef: _contentRef, itemId: _itemId, ...modelResult } = result;
- return { ...modelResult, ...(ref ? { ref } : {}) };
- }
-
- if (result.type !== "file" || result.assetKind !== "pdf") {
- const ref = refFor({ itemId: result.itemId, kind: "item", version: 1 });
-
- return {
- ...omitWorkspaceReadItemId(result),
- ...(ref ? { ref } : {}),
- };
- }
-
- const references = result.location.returned.flatMap((pageNumber) => {
- const ref = refFor({
- itemId: result.itemId,
- kind: "pdf-page",
- pageNumber,
- version: 1,
- });
-
- return ref ? [{ pageNumber, ref }] : [];
- });
-
- return {
- ...omitWorkspaceReadItemId(result),
- content: annotateWorkspaceReadPageHeadings(result.content, references),
- };
- }),
- };
-}
-
-function replaceDocumentContentRefs(
- result: Extract,
- refsByLocation: ReadonlyMap,
-) {
- return result.content.replace(/data-ref="([^"]+)"/g, (attribute, contentRef: string) => {
- const blockId = parseDocumentAiRef(contentRef);
- if (!blockId) return attribute;
- const ref = refsByLocation.get(
- getWorkspaceLocationKey({
- blockId,
- itemId: result.itemId,
- kind: "document-block",
- version: 1,
- }),
- );
- return ref ? `data-ref="${ref}"` : attribute;
- });
-}
-
-function omitWorkspaceReadItemId(
- result: T,
-): Omit {
- const { itemId: _itemId, ...modelResult } = result;
-
- return modelResult;
-}
-
-function annotateWorkspaceReadPageHeadings(
- content: string,
- references: readonly { readonly pageNumber: number; readonly ref: WorkspaceReference }[],
-) {
- const refsByPage = new Map(references.map(({ pageNumber, ref }) => [pageNumber, ref]));
-
- return content.replace(/^## Page (\d+)[ \t]*$/gm, (heading, pageNumberText: string) => {
- const pageNumber = Number(pageNumberText);
- const ref = refsByPage.get(pageNumber);
- if (!ref) {
- return heading;
- }
-
- return `${heading} [ref: ${ref}]`;
- });
-}
diff --git a/src/features/workspaces/documents/document-ai-edits.test.ts b/src/features/workspaces/documents/document-ai-edits.test.ts
index b96e55cb..ff169c92 100644
--- a/src/features/workspaces/documents/document-ai-edits.test.ts
+++ b/src/features/workspaces/documents/document-ai-edits.test.ts
@@ -103,7 +103,7 @@ describe("document AI edits", () => {
expect(rewritten.document.content?.at(-1)).toMatchObject({ type: "paragraph" });
expect(await serializeTiptapDocumentToAiHtml(rewritten.document)).toMatch(
- /<\/ul><\/p>$/,
+ /<\/ul>
<\/p>$/,
);
});
diff --git a/src/features/workspaces/documents/document-ai-edits.ts b/src/features/workspaces/documents/document-ai-edits.ts
index ce6b67fa..56dc7e6b 100644
--- a/src/features/workspaces/documents/document-ai-edits.ts
+++ b/src/features/workspaces/documents/document-ai-edits.ts
@@ -19,9 +19,9 @@ import {
type TiptapDocumentJson,
} from "#/features/workspaces/documents/tiptap-document";
import { getTiptapDocumentSchema } from "#/features/workspaces/documents/tiptap-schema";
-import { workspaceReferenceInputSchema } from "#/features/workspaces/locations/workspace-location";
+import { workspaceUnitRefInputSchema } from "#/features/workspaces/locations/workspace-location";
-const documentRefSchema = workspaceReferenceInputSchema.describe(
+const documentRefSchema = workspaceUnitRefInputSchema.describe(
"Exact ref from a recent document or block read.",
);
export const documentAiHtmlSchema = z
diff --git a/src/features/workspaces/documents/document-ai-html.test.ts b/src/features/workspaces/documents/document-ai-html.test.ts
index ffa56fc4..06c3fc0e 100644
--- a/src/features/workspaces/documents/document-ai-html.test.ts
+++ b/src/features/workspaces/documents/document-ai-html.test.ts
@@ -19,7 +19,7 @@ describe("document AI HTML", () => {
).document;
const html = await serializeTiptapDocumentToAiHtml(document);
- expect(html).toMatch(/^
Notes<\/h1>/);
+ expect(html).toMatch(/^Notes<\/h1>/);
expect(html).toContain("bold");
expect(html).toContain('data-type="inline-math"');
expect(html).toContain('data-type="taskItem"');
@@ -47,7 +47,7 @@ describe("document AI HTML", () => {
);
expect(html).not.toContain("b_modelchosen1");
- expect(html).toMatch(/data-ref="b_[A-Za-z0-9_-]{12}\.r_[A-Za-z0-9_-]{10}"/);
+ expect(html).toMatch(/data-ref="b_[A-Za-z0-9_-]{12}\.r_[A-Za-z0-9_-]{6}"/);
});
it("normalizes malformed but recoverable HTML", () => {
diff --git a/src/features/workspaces/documents/document-ai-html.ts b/src/features/workspaces/documents/document-ai-html.ts
index cb22531a..6eeafeff 100644
--- a/src/features/workspaces/documents/document-ai-html.ts
+++ b/src/features/workspaces/documents/document-ai-html.ts
@@ -16,7 +16,7 @@ import { sha256Base64UrlText } from "#/lib/binary";
const TEXT_NODE = 3;
const documentBlockIdPattern = /^b_[A-Za-z0-9_-]{12}$/;
-const documentAiRefPattern = /^(b_[A-Za-z0-9_-]{12})\.r_([A-Za-z0-9_-]{10})$/;
+const documentAiRefPattern = /^(b_[A-Za-z0-9_-]{12})\.r_([A-Za-z0-9_-]{6})$/;
export class DocumentAiHtmlError extends Error {}
export class WidgetScriptSyntaxError extends DocumentAiHtmlError {}
@@ -108,7 +108,7 @@ export async function createDocumentAiRef(node: ProseMirrorNode) {
// second DOM pass per block per read, and the ref only has to change when
// the block's content does.
const content = JSON.stringify(withTiptapNodeAiRef(node, null).toJSON());
- const revision = (await sha256Base64UrlText(content)).slice(0, 10);
+ const revision = (await sha256Base64UrlText(content)).slice(0, 6);
return `${blockId}.r_${revision}`;
}
@@ -116,16 +116,6 @@ export function parseDocumentAiRef(ref: string) {
return documentAiRefPattern.exec(ref)?.[1] ?? null;
}
-export function readDocumentAiRefRevision(ref: string) {
- return documentAiRefPattern.exec(ref)?.[2] ?? null;
-}
-
-export function readDocumentAiRefs(html: string) {
- return Array.from(html.matchAll(/\sdata-ref="([^"]+)"/g), (match) => match[1]!).filter((ref) =>
- documentAiRefPattern.test(ref),
- );
-}
-
export function ensureTiptapDocumentBlockIds(document: TiptapDocumentJson): {
changed: boolean;
document: TiptapDocumentJson;
@@ -375,6 +365,9 @@ export function applyDocumentCitationLocations(
case "flashcard":
element.setAttribute("data-card-id", location.cardId);
break;
+ case "quiz-question":
+ element.setAttribute("data-question-id", location.questionId);
+ break;
}
}
diff --git a/src/features/workspaces/documents/document-ai-html.worker.test.ts b/src/features/workspaces/documents/document-ai-html.worker.test.ts
index 2741508f..2b755a80 100644
--- a/src/features/workspaces/documents/document-ai-html.worker.test.ts
+++ b/src/features/workspaces/documents/document-ai-html.worker.test.ts
@@ -13,7 +13,7 @@ describe("document AI HTML in Workers", () => {
).document;
expect(await serializeTiptapDocumentToAiHtml(document)).toMatch(
- /^Worker<\/h2>
Schema-safe HTML<\/p>$/,
+ /^
Worker<\/h2>
Schema-safe HTML<\/p>$/,
);
});
});
diff --git a/src/features/workspaces/documents/document-html-chunk.ts b/src/features/workspaces/documents/document-html-chunk.ts
index 0810bda1..9d1991ce 100644
--- a/src/features/workspaces/documents/document-html-chunk.ts
+++ b/src/features/workspaces/documents/document-html-chunk.ts
@@ -17,18 +17,19 @@ export interface DocumentHtmlChunk {
}
export interface DocumentHtmlChunkReadInput {
- expectedRevision?: string;
offset: number;
+ /** Stop after this many blocks even if the character budget has room. */
+ maxBlocks?: number;
}
export type DocumentHtmlChunkReadResult =
- | { status: "content_changed" }
| { status: "invalid_offset" }
- | ({ revision: string; status: "ready" } & DocumentHtmlChunk);
+ | ({ status: "ready" } & DocumentHtmlChunk);
export async function readDocumentHtmlChunk(
document: ProseMirrorNode,
offset: number,
+ maxBlocks?: number,
): Promise {
if (offset < 0 || offset >= document.childCount) {
return undefined;
@@ -38,6 +39,7 @@ export async function readDocumentHtmlChunk(
let characters = 0;
let endOffset = offset;
while (endOffset < document.childCount) {
+ if (maxBlocks !== undefined && endOffset - offset >= maxBlocks) break;
const block = await serializeTiptapNodeToAiHtml(document.child(endOffset));
const separatorCharacters = content.length > 0 ? 1 : 0;
if (
diff --git a/src/features/workspaces/documents/document-session.ts b/src/features/workspaces/documents/document-session.ts
index 3b8c63c6..98049c23 100644
--- a/src/features/workspaces/documents/document-session.ts
+++ b/src/features/workspaces/documents/document-session.ts
@@ -51,7 +51,7 @@ import {
commitWorkspaceDocumentCheckpoint,
readWorkspaceDocumentCheckpoint,
} from "#/features/workspaces/persistence/workspace-document-checkpoints";
-import { sha256Base64Url, sha256Base64UrlText } from "#/lib/binary";
+import { sha256Base64UrlText } from "#/lib/binary";
const persistedYDocUpdateKey = "document-session:yjs-update";
const latestDocumentEditReceiptKey = "document-session:ai-edit-receipt:latest";
@@ -354,14 +354,10 @@ export class DocumentSession extends YServer {
async readHtmlChunk(input: DocumentHtmlChunkReadInput): Promise {
this.assertActive();
- const { document, stateVector } = await this.getReferencedDocumentSnapshot();
- const revision = await sha256Base64Url(stateVector);
- if (input.expectedRevision && input.expectedRevision !== revision) {
- return { status: "content_changed" };
- }
+ const { document } = await this.getReferencedDocumentSnapshot();
- const chunk = await readDocumentHtmlChunk(document, input.offset);
- return chunk ? { ...chunk, revision, status: "ready" } : { status: "invalid_offset" };
+ const chunk = await readDocumentHtmlChunk(document, input.offset, input.maxBlocks);
+ return chunk ? { ...chunk, status: "ready" } : { status: "invalid_offset" };
}
/**
diff --git a/src/features/workspaces/documents/tiptap-schema.ts b/src/features/workspaces/documents/tiptap-schema.ts
index fe794b81..fdf78a85 100644
--- a/src/features/workspaces/documents/tiptap-schema.ts
+++ b/src/features/workspaces/documents/tiptap-schema.ts
@@ -34,6 +34,7 @@ export const Citation = Node.create({
itemId: { default: null, parseHTML: (el) => el.getAttribute("data-item-id") },
blockId: { default: null, parseHTML: (el) => el.getAttribute("data-block-id") },
cardId: { default: null, parseHTML: (el) => el.getAttribute("data-card-id") },
+ questionId: { default: null, parseHTML: (el) => el.getAttribute("data-question-id") },
pageNumber: {
default: null,
parseHTML: (el) => {
@@ -55,6 +56,7 @@ export const Citation = Node.create({
"data-item-id": node.attrs.itemId,
...(node.attrs.blockId ? { "data-block-id": String(node.attrs.blockId) } : {}),
...(node.attrs.cardId ? { "data-card-id": String(node.attrs.cardId) } : {}),
+ ...(node.attrs.questionId ? { "data-question-id": String(node.attrs.questionId) } : {}),
...(node.attrs.pageNumber ? { "data-page": String(node.attrs.pageNumber) } : {}),
},
];
@@ -67,13 +69,15 @@ export function getWorkspaceCitationLocation(
const itemId = typeof attrs.itemId === "string" ? attrs.itemId : null;
if (!itemId) return undefined;
- const location = attrs.cardId
- ? { cardId: attrs.cardId, itemId, kind: "flashcard", version: 1 }
- : attrs.blockId
- ? { blockId: attrs.blockId, itemId, kind: "document-block", version: 1 }
- : attrs.pageNumber
- ? { itemId, kind: "pdf-page", pageNumber: attrs.pageNumber, version: 1 }
- : { itemId, kind: "item", version: 1 };
+ const location = attrs.questionId
+ ? { itemId, kind: "quiz-question", questionId: attrs.questionId, version: 1 }
+ : attrs.cardId
+ ? { cardId: attrs.cardId, itemId, kind: "flashcard", version: 1 }
+ : attrs.blockId
+ ? { blockId: attrs.blockId, itemId, kind: "document-block", version: 1 }
+ : attrs.pageNumber
+ ? { itemId, kind: "pdf-page", pageNumber: attrs.pageNumber, version: 1 }
+ : { itemId, kind: "item", version: 1 };
const parsed = workspaceLocationSchema.safeParse(location);
return parsed.success ? parsed.data : undefined;
diff --git a/src/features/workspaces/locations/workspace-location-context.test.tsx b/src/features/workspaces/locations/workspace-location-context.test.tsx
index f8dad677..6c80feeb 100644
--- a/src/features/workspaces/locations/workspace-location-context.test.tsx
+++ b/src/features/workspaces/locations/workspace-location-context.test.tsx
@@ -30,6 +30,7 @@ describe("WorkspaceLocationProvider", () => {
type: "file",
name: "Book.pdf",
color: null,
+ refKey: "ref-file-1",
metadataJson: {},
sortOrder: 1,
createdAt: "2026-08-13T00:00:00.000Z",
diff --git a/src/features/workspaces/locations/workspace-location-context.tsx b/src/features/workspaces/locations/workspace-location-context.tsx
index fceaae93..c59ea90f 100644
--- a/src/features/workspaces/locations/workspace-location-context.tsx
+++ b/src/features/workspaces/locations/workspace-location-context.tsx
@@ -2,7 +2,11 @@ import { FileQuestion, type LucideIcon } from "lucide-react";
import { createContext, type ReactNode, use, useCallback, useState } from "react";
import { toast } from "sonner";
-import type { WorkspaceLocation } from "#/features/workspaces/locations/workspace-location";
+import {
+ parseWorkspaceAddress,
+ resolveWorkspaceAddressLocation,
+ type WorkspaceLocation,
+} from "#/features/workspaces/locations/workspace-location";
import { getWorkspaceItemDisplay } from "#/features/workspaces/model/item-display";
import type { WorkspaceItem } from "#/features/workspaces/contracts";
@@ -24,6 +28,8 @@ type WorkspaceLocationContextValue = {
completeRevealRequest: (request: WorkspaceLocationRevealRequest, revealed: boolean) => void;
getItem: (itemId: string) => WorkspaceItem | undefined;
getPresentation: (location: WorkspaceLocation) => WorkspaceLocationPresentation;
+ /** Resolves a self-describing address like `Xk7p2Qa9/p5` against the live workspace. */
+ resolveAddress: (ref: unknown) => WorkspaceLocation | undefined;
reveal: (location: WorkspaceLocation) => boolean;
revealRequest: WorkspaceLocationRevealRequest | null;
};
@@ -56,6 +62,16 @@ export function WorkspaceLocationProvider({
getItem(itemId) {
return itemsById.get(itemId);
},
+ resolveAddress(ref) {
+ const address = typeof ref === "string" ? parseWorkspaceAddress(ref) : undefined;
+ if (!address) return undefined;
+ for (const item of itemsById.values()) {
+ if (item.refKey === address.refKey) {
+ return resolveWorkspaceAddressLocation(item, address);
+ }
+ }
+ return undefined;
+ },
getPresentation(location) {
const item = itemsById.get(location.itemId);
const itemName = item?.name ?? "Source unavailable";
@@ -95,6 +111,9 @@ function getWorkspaceLocatorLabel(location: WorkspaceLocation) {
return `p. ${location.pageNumber}`;
case "document-block":
case "flashcard":
+ case "quiz-question":
+ // Content-positional labels ("Card 3", "Question 3") need the item's
+ // current content, so the citation component supplies them.
return undefined;
}
}
diff --git a/src/features/workspaces/locations/workspace-location.test.ts b/src/features/workspaces/locations/workspace-location.test.ts
index 8ae8010d..85325813 100644
--- a/src/features/workspaces/locations/workspace-location.test.ts
+++ b/src/features/workspaces/locations/workspace-location.test.ts
@@ -1,108 +1,95 @@
import { describe, expect, it } from "vitest";
import {
- createWorkspaceReferenceRecords,
- getWorkspaceLocationKey,
- indexWorkspaceReferenceRecords,
- parseWorkspaceReference,
+ parseWorkspaceAddress,
+ parseWorkspaceUnitRef,
+ resolveWorkspaceAddressLocation,
workspaceLocationSchema,
} from "#/features/workspaces/locations/workspace-location";
-describe("workspace location", () => {
- it.each([
- [{ itemId: "item-1", kind: "item", version: 1 }, "1:item:item-1"],
- [{ itemId: "item-1", kind: "pdf-page", pageNumber: 12, version: 1 }, "1:pdf-page:item-1:12"],
- [
- {
- itemId: "item-1",
- kind: "flashcard",
- cardId: "f67080f9-0158-4565-86a9-4c90ed6809d2",
- version: 1,
- },
- "1:flashcard:item-1:f67080f9-0158-4565-86a9-4c90ed6809d2",
- ],
- [
- { blockId: "b_abcdefghijkl", itemId: "item-1", kind: "document-block", version: 1 },
- "1:document-block:item-1:b_abcdefghijkl",
- ],
- ])("parses and keys %o", (input, expectedKey) => {
- const result = workspaceLocationSchema.safeParse(input);
-
- expect(result.success).toBe(true);
- if (result.success) {
- expect(getWorkspaceLocationKey(result.data)).toBe(expectedKey);
- }
- });
-
- it.each([
- { itemId: "", kind: "item", version: 1 },
- { itemId: "item-1", kind: "pdf-page", pageNumber: 0, version: 1 },
- { cardId: "not-a-uuid", itemId: "item-1", kind: "flashcard", version: 1 },
- { blockId: "block-1", itemId: "item-1", kind: "document-block", version: 1 },
- { itemId: "item-1", kind: "item", version: 2 },
- { extra: true, itemId: "item-1", kind: "item", version: 1 },
- ])("rejects invalid location %o", (input) => {
- expect(workspaceLocationSchema.safeParse(input).success).toBe(false);
- });
-});
-
-describe("workspace reference", () => {
- it("creates an 11-character opaque reference", () => {
- const location = { itemId: "item-1", kind: "item", version: 1 } as const;
- const [{ ref }] = createWorkspaceReferenceRecords([location]);
-
- expect(ref).toMatch(/^wr_[0-9A-Za-z]{8}$/);
- expect(ref).toHaveLength(11);
- expect(parseWorkspaceReference(ref)).toBe(ref);
- });
-
- it("reuses one ref for the same durable location", () => {
- const location = { itemId: "item-1", kind: "pdf-page", pageNumber: 7, version: 1 } as const;
- const records = createWorkspaceReferenceRecords([location, { ...location }], {
- createCandidate: () => "wr_AAAAAAAA",
+describe("workspace addresses", () => {
+ it("parses item, unit, and revisioned forms", () => {
+ expect(parseWorkspaceAddress("Xk7p2Qa9")).toEqual({ refKey: "Xk7p2Qa9" });
+ expect(parseWorkspaceAddress("Xk7p2Qa9/p12")).toEqual({ refKey: "Xk7p2Qa9", unit: "p12" });
+ expect(parseWorkspaceAddress("Xk7p2Qa9/b_x7Kp2Qa9x8Lm.r_4f2a1b")).toEqual({
+ refKey: "Xk7p2Qa9",
+ unit: "b_x7Kp2Qa9x8Lm",
+ revision: "4f2a1b",
});
-
- expect(records).toEqual([{ location, ref: "wr_AAAAAAAA" }]);
- });
-
- it("retries a colliding candidate", () => {
- const candidates = ["wr_AAAAAAAA", "wr_AAAAAAAA", "wr_BBBBBBBB"];
- const records = createWorkspaceReferenceRecords(
- [
- { itemId: "item-1", kind: "item", version: 1 },
- { itemId: "item-2", kind: "item", version: 1 },
- ],
- {
- createCandidate: () => candidates.shift() ?? "wr_CCCCCCCC",
- },
- );
-
- expect(records.map(({ ref }) => ref)).toEqual(["wr_AAAAAAAA", "wr_BBBBBBBB"]);
+ expect(parseWorkspaceAddress("not an address")).toBeUndefined();
+ expect(parseWorkspaceAddress("wr_7Kp2Qa9x")).toBeUndefined();
});
- it("retains editable revisions and makes conflicting transcript refs unusable", () => {
- const location = {
- blockId: "b_abcdefghijkl",
+ it("interprets units against the item's type", () => {
+ const address = parseWorkspaceAddress("Xk7p2Qa9/p12")!;
+ expect(resolveWorkspaceAddressLocation({ id: "item-1", type: "file" }, address)).toEqual({
itemId: "item-1",
- kind: "document-block",
+ kind: "pdf-page",
+ pageNumber: 12,
version: 1,
- } as const;
- const [record] = createWorkspaceReferenceRecords([{ location, revision: "0123456789" }], {
- createCandidate: () => "wr_AAAAAAAA",
});
+ // The same unit means nothing on a document.
+ expect(
+ resolveWorkspaceAddressLocation({ id: "item-1", type: "document" }, address),
+ ).toBeUndefined();
- expect(record).toEqual({ location, ref: "wr_AAAAAAAA", revision: "0123456789" });
expect(
- indexWorkspaceReferenceRecords([record!, { ...record!, revision: "9876543210" }]).get(
- record!.ref,
+ resolveWorkspaceAddressLocation(
+ { id: "item-1", type: "flashcard" },
+ parseWorkspaceAddress("Xk7p2Qa9/c_9xKp2Qab")!,
+ ),
+ ).toEqual({ cardId: "c_9xKp2Qab", itemId: "item-1", kind: "flashcard", version: 1 });
+ expect(
+ resolveWorkspaceAddressLocation(
+ { id: "item-1", type: "quiz" },
+ parseWorkspaceAddress("Xk7p2Qa9/f67080f9-0158-4565-86a9-4c90ed6809d2")!,
+ ),
+ ).toEqual({
+ itemId: "item-1",
+ kind: "quiz-question",
+ questionId: "f67080f9-0158-4565-86a9-4c90ed6809d2",
+ version: 1,
+ });
+ expect(
+ resolveWorkspaceAddressLocation(
+ { id: "item-1", type: "document" },
+ parseWorkspaceAddress("Xk7p2Qa9")!,
),
- ).toBeNull();
+ ).toEqual({ itemId: "item-1", kind: "item", version: 1 });
});
- it.each(["", "wr_short", "xx_AAAAAAAA", "wr_!!!!!!!!", "wr_AAAAAAAAA"])(
- "rejects malformed ref %s",
- (input) => {
- expect(parseWorkspaceReference(input)).toBeUndefined();
- },
- );
+ it("parses edit unit refs with their revision", () => {
+ expect(parseWorkspaceUnitRef("b_x7Kp2Qa9x8Lm.r_4f2a1b")).toEqual({
+ unit: "b_x7Kp2Qa9x8Lm",
+ revision: "4f2a1b",
+ });
+ expect(parseWorkspaceUnitRef("b_x7Kp2Qa9x8Lm")).toBeUndefined();
+ });
+
+ it("keeps persisted locations validating legacy and short entry ids", () => {
+ expect(
+ workspaceLocationSchema.safeParse({
+ cardId: "f67080f9-0158-4565-86a9-4c90ed6809d2",
+ itemId: "item-1",
+ kind: "flashcard",
+ version: 1,
+ }).success,
+ ).toBe(true);
+ expect(
+ workspaceLocationSchema.safeParse({
+ cardId: "c_9xKp2Qab",
+ itemId: "item-1",
+ kind: "flashcard",
+ version: 1,
+ }).success,
+ ).toBe(true);
+ expect(
+ workspaceLocationSchema.safeParse({
+ cardId: "not-an-id",
+ itemId: "item-1",
+ kind: "flashcard",
+ version: 1,
+ }).success,
+ ).toBe(false);
+ });
});
diff --git a/src/features/workspaces/locations/workspace-location.ts b/src/features/workspaces/locations/workspace-location.ts
index 67f9dc81..89f94fdc 100644
--- a/src/features/workspaces/locations/workspace-location.ts
+++ b/src/features/workspaces/locations/workspace-location.ts
@@ -3,19 +3,30 @@ import { z } from "zod";
const WORKSPACE_REFERENCE_ALPHABET =
"0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
-const WORKSPACE_REFERENCE_RANDOM_LENGTH = 8;
-const WORKSPACE_REFERENCE_COLLISION_ATTEMPTS = 32;
-const createRandomWorkspaceReferenceSuffix = customAlphabet(
- WORKSPACE_REFERENCE_ALPHABET,
- WORKSPACE_REFERENCE_RANDOM_LENGTH,
-);
+/** Mints the short, durable, model-facing handle a workspace item keeps for life. */
+export const createWorkspaceItemRefKey = customAlphabet(WORKSPACE_REFERENCE_ALPHABET, 8);
const workspaceLocationItemIdSchema = z.string().trim().min(1);
+const createWorkspaceEntryIdSuffix = customAlphabet(WORKSPACE_REFERENCE_ALPHABET, 8);
+
+/** Mints the id of one card or question, e.g. `c_9xKp2Qab`. */
+export function createWorkspaceEntryId(prefix: "c" | "q") {
+ return `${prefix}_${createWorkspaceEntryIdSuffix()}`;
+}
+
/**
- * Durable, versioned pointer to content inside a workspace.
- *
- * Short AI-facing references are aliases for this value and must never replace
- * it in persisted application state.
+ * One flashcard or quiz-question id. Early content minted UUIDs; everything
+ * since mints the short prefixed form, and both stay valid ids forever.
+ */
+export const workspaceEntryIdSchema = z.union([
+ z.string().regex(/^[cq]_[0-9A-Za-z]{8}$/),
+ z.uuid(),
+]);
+
+/**
+ * Durable, versioned pointer to content inside a workspace, as persisted by
+ * document and chat citations. Model-facing addresses parse into this against
+ * the item they name.
*/
export const workspaceLocationSchema = z.discriminatedUnion("kind", [
z.strictObject({
@@ -38,7 +49,13 @@ export const workspaceLocationSchema = z.discriminatedUnion("kind", [
z.strictObject({
itemId: workspaceLocationItemIdSchema,
kind: z.literal("flashcard"),
- cardId: z.uuid(),
+ cardId: workspaceEntryIdSchema,
+ version: z.literal(1),
+ }),
+ z.strictObject({
+ itemId: workspaceLocationItemIdSchema,
+ kind: z.literal("quiz-question"),
+ questionId: workspaceEntryIdSchema,
version: z.literal(1),
}),
]);
@@ -46,127 +63,89 @@ export const workspaceLocationSchema = z.discriminatedUnion("kind", [
/** A parsed durable workspace location. */
export type WorkspaceLocation = Readonly>;
-/** Schema for the exact short reference the model is allowed to copy. */
-export const workspaceReferenceInputSchema = z.string().regex(/^wr_[0-9A-Za-z]{8}$/);
-export const workspaceReferenceSchema = workspaceReferenceInputSchema.brand<"WorkspaceReference">();
-
-/** Short model-facing alias for a durable workspace location. */
-export type WorkspaceReference = z.output;
-
-/** Schema for a durable location retained behind a short reference. */
-export const workspaceReferenceRecordSchema = z.strictObject({
- location: workspaceLocationSchema,
- ref: workspaceReferenceSchema,
- revision: z
- .string()
- .regex(/^[A-Za-z0-9_-]{10}$/)
- .optional(),
-});
-
-/** Durable record retained behind a short workspace reference. */
-export type WorkspaceReferenceRecord = Readonly>;
-
/**
- * Produces the canonical in-memory key for a workspace location.
+ * The model-facing address grammar: `refKey[/unit][.r_revision]`.
*
- * @param location - Parsed workspace location.
- * @returns A collision-free key within location schema version 1.
+ * `refKey` is the item's durable 8-character handle. `unit` names one piece of
+ * it — `p5` a physical page, `b_…` a document block, a card or question id for
+ * study items — and is interpreted against the item's type, so the token never
+ * has to encode what kind of thing it names. `.r_…` carries the 6-character
+ * content revision an edit must present. The whole string is self-describing:
+ * nothing has to be minted, stored, or kept alive server-side for it to
+ * resolve, so an address from any point in a conversation keeps working.
*/
-export function getWorkspaceLocationKey(location: WorkspaceLocation) {
- switch (location.kind) {
- case "item":
- return `1:item:${location.itemId}`;
- case "pdf-page":
- return `1:pdf-page:${location.itemId}:${location.pageNumber}`;
- case "document-block":
- return `1:document-block:${location.itemId}:${location.blockId}`;
- case "flashcard":
- return `1:flashcard:${location.itemId}:${location.cardId}`;
- }
-}
+const workspaceAddressPattern =
+ /^([0-9A-Za-z]{8})(?:\/([A-Za-z0-9_-]{1,40}?))?(?:\.r_([A-Za-z0-9_-]{6}))?$/;
-/**
- * Parses an untrusted short workspace reference.
- *
- * @param input - Untrusted model or persisted value.
- * @returns A branded reference when valid.
- */
-export function parseWorkspaceReference(input: unknown) {
- const parsed = workspaceReferenceSchema.safeParse(input);
+export const workspaceAddressInputSchema = z.string().regex(workspaceAddressPattern);
- return parsed.success ? parsed.data : undefined;
+export interface WorkspaceAddress {
+ refKey: string;
+ unit?: string;
+ revision?: string;
}
-/** Index app-issued refs while making collisions unusable. */
-export function indexWorkspaceReferenceRecords(
- records: readonly WorkspaceReferenceRecord[],
-): ReadonlyMap {
- const index = new Map();
- for (const record of records) {
- const existing = index.get(record.ref);
- if (existing === undefined) {
- index.set(record.ref, record);
- } else if (
- existing &&
- (getWorkspaceLocationKey(existing.location) !== getWorkspaceLocationKey(record.location) ||
- existing.revision !== record.revision)
- ) {
- index.set(record.ref, null);
- }
- }
- return index;
+export function parseWorkspaceAddress(input: unknown): WorkspaceAddress | undefined {
+ if (typeof input !== "string") return undefined;
+ const match = workspaceAddressPattern.exec(input.trim());
+ if (!match) return undefined;
+ return {
+ refKey: match[1]!,
+ ...(match[2] ? { unit: match[2] } : {}),
+ ...(match[3] ? { revision: match[3] } : {}),
+ };
}
/**
- * Creates deduplicated, collision-checked refs for durable locations.
- *
- * The optional candidate source is an internal test seam. Production callers
- * should use the default cryptographically strong Nano ID source.
+ * Interprets an address's unit against the item it names.
*
- * @param locations - Durable locations in desired record order.
- * @param options - Optional candidate source for deterministic verification.
- * @returns One reference record per distinct location.
+ * @returns The durable location, or undefined when the unit cannot belong to
+ * an item of this type.
*/
-export function createWorkspaceReferenceRecords(
- targets: readonly (WorkspaceLocation | { location: WorkspaceLocation; revision: string })[],
- options: { readonly createCandidate?: () => string } = {},
-): WorkspaceReferenceRecord[] {
- const createCandidate =
- options.createCandidate ?? (() => `wr_${createRandomWorkspaceReferenceSuffix()}`);
- const locationKeys = new Set();
- const refs = new Set();
- const records: WorkspaceReferenceRecord[] = [];
-
- for (const target of targets) {
- const { location, revision } =
- "location" in target ? target : { location: target, revision: undefined };
- const locationKey = getWorkspaceLocationKey(location);
- if (locationKeys.has(locationKey)) {
- continue;
- }
-
- let allocatedRef: WorkspaceReference | undefined;
- for (let attempt = 0; attempt < WORKSPACE_REFERENCE_COLLISION_ATTEMPTS; attempt += 1) {
- const ref = parseWorkspaceReference(createCandidate());
- if (!ref) {
- throw new Error("Workspace reference candidate source returned an invalid value.");
- }
- if (refs.has(ref)) {
- continue;
- }
-
- allocatedRef = ref;
- break;
- }
+export function resolveWorkspaceAddressLocation(
+ item: { id: string; type: "document" | "file" | "flashcard" | "folder" | "quiz" },
+ address: WorkspaceAddress,
+): WorkspaceLocation | undefined {
+ if (address.unit === undefined) {
+ return { itemId: item.id, kind: "item", version: 1 };
+ }
+ if (item.type === "file") {
+ const page = /^p([1-9]\d{0,5})$/.exec(address.unit);
+ return page
+ ? { itemId: item.id, kind: "pdf-page", pageNumber: Number(page[1]), version: 1 }
+ : undefined;
+ }
+ if (item.type === "document") {
+ return /^b_[A-Za-z0-9_-]{12}$/.test(address.unit)
+ ? { blockId: address.unit, itemId: item.id, kind: "document-block", version: 1 }
+ : undefined;
+ }
+ if (item.type === "flashcard") {
+ const cardId = workspaceEntryIdSchema.safeParse(address.unit);
+ return cardId.success
+ ? { cardId: cardId.data, itemId: item.id, kind: "flashcard", version: 1 }
+ : undefined;
+ }
+ if (item.type === "quiz") {
+ const questionId = workspaceEntryIdSchema.safeParse(address.unit);
+ return questionId.success
+ ? { itemId: item.id, kind: "quiz-question", questionId: questionId.data, version: 1 }
+ : undefined;
+ }
+ return undefined;
+}
- if (!allocatedRef) {
- throw new Error("Unable to allocate a collision-free workspace reference.");
- }
+/**
+ * A unit ref as copied from a read into an edit: `unit.r_revision`. The item
+ * is already named by the edit call's path, so the ref stays item-relative.
+ */
+const workspaceUnitRefPattern = /^([A-Za-z0-9_-]{1,40}?)\.r_([A-Za-z0-9_-]{6})$/;
- locationKeys.add(locationKey);
- refs.add(allocatedRef);
- records.push({ location, ref: allocatedRef, ...(revision ? { revision } : {}) });
- }
+export const workspaceUnitRefInputSchema = z.string().regex(workspaceUnitRefPattern);
- return records;
+export function parseWorkspaceUnitRef(
+ input: string,
+): { unit: string; revision: string } | undefined {
+ const match = workspaceUnitRefPattern.exec(input);
+ return match ? { unit: match[1]!, revision: match[2]! } : undefined;
}
diff --git a/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap b/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap
index ef7c7572..5f94c410 100644
--- a/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap
+++ b/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap
@@ -105,7 +105,7 @@ exports[`workspace tool surface > workspace_create_items input schema is stable
"description": "Document to create.",
"properties": {
"initialContent": {
- "description": "Optional initial HTML content. Use semantic HTML with paragraphs, h1-h4, blockquotes, lists, code blocks, horizontal rules, tables, links, and standard text marks. This is HTML, so math is markup rather than delimiters: use or , and keep dollar signs out of the data-latex value. Put every subscript and superscript (exponents like 10^8, indices like x_1) inside math rather than / tags. Chemistry renders with \\ce{...} (e.g. \\ce{CH4 + 2 O2 -> CO2 + 2 H2O}) and quantities with units render with \\pu{...} (e.g. \\pu{9.81 m/s^2}), both inside data-latex. Write literal money as plain text ($30, never \\$30) — a backslash before a dollar sign shows on screen in HTML. For checkboxes, use Item
. Documents cannot hold images: never use ![]()
or , and describe the visual in words instead. Cite workspace sources in documents exactly as in a chat reply, with Item
. Documents cannot hold images: never use ![]()
or , and describe the visual in words instead. Cite workspace sources in documents exactly as in a chat reply, with Item
. Documents cannot hold images: never use ![]()
or , and describe the visual in words instead. Cite workspace sources in documents exactly as in a chat reply, with Item
. Documents cannot hold images: never use ![]()
or , and describe the visual in words instead. Cite workspace sources in documents exactly as in a chat reply, with {
const refs = readDocumentCitationRefs(input.html);
- if (refs.length === 0 || !input.context.resolveWorkspaceReferences) {
+ if (refs.length === 0) {
return input.html;
}
- const records = await input.context.resolveWorkspaceReferences(refs);
- const locations = new Map(
- [...indexWorkspaceReferenceRecords(records)].flatMap(([ref, record]) =>
- record ? [[ref, record.location] as const] : [],
- ),
- );
+ const locations = new Map();
+ for (const ref of new Set(refs)) {
+ const address = parseWorkspaceAddress(ref);
+ if (!address) continue;
+ const resolved = await getWorkspaceItemByRefKey({
+ refKey: address.refKey,
+ workspaceId: input.context.workspaceId,
+ });
+ const location = resolved ? resolveWorkspaceAddressLocation(resolved.item, address) : undefined;
+ if (location) locations.set(ref, location);
+ }
return applyDocumentCitationLocations(input.html, locations);
}
diff --git a/src/features/workspaces/operations/edit-item.ts b/src/features/workspaces/operations/edit-item.ts
index 30cde027..d9e65039 100644
--- a/src/features/workspaces/operations/edit-item.ts
+++ b/src/features/workspaces/operations/edit-item.ts
@@ -12,20 +12,22 @@ import { resolveDocumentCitations } from "#/features/workspaces/operations/docum
import {
applyFlashcardEdits,
type FlashcardEdit,
- type FlashcardEditTarget,
} from "#/features/workspaces/flashcards/flashcard-edits";
import { updateFlashcardSet } from "#/features/workspaces/flashcards/flashcard-persistence";
+import { applyQuizEdits, type QuizEdit } from "#/features/workspaces/quizzes/quiz-edits";
+import { updateQuizSet } from "#/features/workspaces/quizzes/quiz-persistence";
+import type { OrderedEntryEditTarget } from "#/features/workspaces/content/ordered-entry-edits";
import {
- indexWorkspaceReferenceRecords,
- parseWorkspaceReference,
- type WorkspaceReferenceRecord,
+ parseWorkspaceUnitRef,
+ workspaceEntryIdSchema,
} from "#/features/workspaces/locations/workspace-location";
type EditWorkspaceItemFailureCode = (typeof editWorkspaceItemFailureCodes)[number];
export type EditWorkspaceItemOperationInput =
| { edits: DocumentAiEdit[]; path: string; type: "document" }
- | { edits: FlashcardEdit[]; path: string; type: "flashcard" };
+ | { edits: FlashcardEdit[]; path: string; type: "flashcard" }
+ | { edits: QuizEdit[]; path: string; type: "quiz" };
interface EditWorkspaceItemFailure {
code: EditWorkspaceItemFailureCode;
@@ -37,7 +39,7 @@ export interface EditWorkspaceItemOperationResult {
applied: number;
failed: EditWorkspaceItemFailure[];
itemId?: string;
- itemType?: "document" | "flashcard";
+ itemType?: "document" | "flashcard" | "quiz";
lineChanges?: DocumentEditLineChanges;
path: string;
}
@@ -77,66 +79,51 @@ export async function editWorkspaceItemOperation(
};
}
- if (input.type === "flashcard") {
- const targets = await resolveEditTargets(
- accessContext,
- input.edits,
- (record) =>
- record.location.kind === "flashcard" &&
- record.location.itemId === resolution.item.id &&
- record.revision
- ? { cardId: record.location.cardId, revision: record.revision }
- : undefined,
- );
+ if (input.type === "flashcard" || input.type === "quiz") {
+ const itemId = resolution.item.id;
+ const targets = collectEntryEditTargets(input.edits);
const { env } = await import("cloudflare:workers");
- const result = await updateFlashcardSet(
- env,
- {
- actorUserId: accessContext.actor.userId,
- itemId: resolution.item.id,
- workspaceId: accessContext.workspaceId,
- },
- async (content) => {
- const applied = await applyFlashcardEdits(content, input.edits, targets);
- return { changed: applied.applied > 0, content: applied.content, result: applied };
- },
- );
+ const persistenceInput = {
+ actorUserId: accessContext.actor.userId,
+ itemId,
+ workspaceId: accessContext.workspaceId,
+ };
+ const result =
+ input.type === "flashcard"
+ ? await updateFlashcardSet(env, persistenceInput, async (content) => {
+ const applied = await applyFlashcardEdits(content, input.edits, targets);
+ return { changed: applied.applied > 0, content: applied.content, result: applied };
+ })
+ : await updateQuizSet(env, persistenceInput, async (content) => {
+ const applied = await applyQuizEdits(content, input.edits, targets);
+ return { changed: applied.applied > 0, content: applied.content, result: applied };
+ });
return {
applied: result.applied,
failed: result.failed,
- itemId: resolution.item.id,
- itemType: "flashcard",
+ itemId,
+ itemType: input.type,
path: resolution.path,
};
}
- const [targets, documentSession] = await Promise.all([
- resolveEditTargets(accessContext, input.edits, (record) =>
- record.location.kind === "document-block" &&
- record.location.itemId === resolution.item.id &&
- record.revision
- ? `${record.location.blockId}.r_${record.revision}`
- : undefined,
- ),
- getDocumentSession({
- itemId: resolution.item.id,
- workspaceId: accessContext.workspaceId,
- }),
- ]);
+ const documentSession = await getDocumentSession({
+ itemId: resolution.item.id,
+ workspaceId: accessContext.workspaceId,
+ });
const result = await documentSession.applyEdits({
edits: await Promise.all(
- input.edits.map(async (edit) => {
- const contentEdit = replacePublicRefs(edit, targets);
- return "html" in contentEdit
+ input.edits.map(async (edit) =>
+ "html" in edit
? {
- ...contentEdit,
+ ...edit,
html: await resolveDocumentCitations({
context: accessContext,
- html: contentEdit.html,
+ html: edit.html,
}),
}
- : contentEdit;
- }),
+ : edit,
+ ),
),
operationId: accessContext.operationId,
});
@@ -151,52 +138,27 @@ export async function editWorkspaceItemOperation(
};
}
-async function resolveEditTargets<
- TEdit extends { ref: string; afterRef?: string; beforeRef?: string },
- TTarget,
->(
- context: WorkspaceAccessContext,
- edits: readonly TEdit[],
- toTarget: (record: WorkspaceReferenceRecord) => TTarget | undefined,
+/**
+ * Parses every entry ref an edit batch mentions. A unit ref is self-contained
+ * — entry id plus content revision — so targeting needs no lookup; a ref whose
+ * unit is not an entry id simply resolves to nothing and the edit engine
+ * reports `ref_not_found` at the right index.
+ */
+function collectEntryEditTargets(
+ edits: readonly { ref: string; afterRef?: string; beforeRef?: string }[],
) {
- const refs = [...new Set(edits.flatMap(getReferencedRefs))];
- const records =
- refs.length > 0 && context.resolveWorkspaceReferences
- ? await context.resolveWorkspaceReferences(refs)
- : [];
- const recordsByRef = indexWorkspaceReferenceRecords(records);
- const targets = new Map();
- for (const ref of refs) {
- const parsedRef = parseWorkspaceReference(ref);
- const record = parsedRef ? recordsByRef.get(parsedRef) : undefined;
- const target = record ? toTarget(record) : undefined;
- if (target) targets.set(ref, target);
+ const targets = new Map();
+ for (const edit of edits) {
+ for (const ref of [edit.ref, edit.beforeRef, edit.afterRef]) {
+ if (!ref || targets.has(ref)) continue;
+ const parsed = parseWorkspaceUnitRef(ref);
+ if (!parsed || !workspaceEntryIdSchema.safeParse(parsed.unit).success) continue;
+ targets.set(ref, { entryId: parsed.unit, revision: parsed.revision });
+ }
}
-
return targets;
}
-function replacePublicRefs(
- edit: TEdit,
- targets: ReadonlyMap,
-): TEdit {
- // Unresolved refs stay invalid so the document engine reports them at their original edit index.
- return {
- ...edit,
- ref: targets.get(edit.ref) ?? edit.ref,
- ...(edit.beforeRef ? { beforeRef: targets.get(edit.beforeRef) ?? edit.beforeRef } : {}),
- ...(edit.afterRef ? { afterRef: targets.get(edit.afterRef) ?? edit.afterRef } : {}),
- };
-}
-
-function getReferencedRefs(edit: { ref: string; afterRef?: string; beforeRef?: string }) {
- return [
- edit.ref,
- ...(edit.beforeRef ? [edit.beforeRef] : []),
- ...(edit.afterRef ? [edit.afterRef] : []),
- ];
-}
-
async function getDocumentSession(input: { itemId: string; workspaceId: string }) {
const { env } = await import("cloudflare:workers");
diff --git a/src/features/workspaces/operations/read-items.ts b/src/features/workspaces/operations/read-items.ts
index fafde068..8f4ba239 100644
--- a/src/features/workspaces/operations/read-items.ts
+++ b/src/features/workspaces/operations/read-items.ts
@@ -6,13 +6,10 @@ import {
} from "#/features/workspaces/content/workspace-content-contract";
import { readWorkspaceContent } from "#/features/workspaces/content/workspace-content-reader";
import { recordWorkspaceFileReadOutcomes } from "#/features/workspaces/content/workspace-read-observability";
-import { createWorkspaceReadReferences } from "#/features/workspaces/content/workspace-read-references";
import { getDocumentSessionFromEnv } from "#/features/workspaces/document-session-access";
import { readFlashcardViewer } from "#/features/workspaces/flashcards/flashcard-study-persistence";
-import {
- indexWorkspaceReferenceRecords,
- parseWorkspaceReference,
-} from "#/features/workspaces/locations/workspace-location";
+import { readQuizViewer } from "#/features/workspaces/quizzes/quiz-study-persistence";
+import { getWorkspaceItemByRefKey } from "#/features/workspaces/persistence/workspace-items";
import type { WorkspaceAccessContext } from "#/features/workspaces/operations/workspace-access-context";
import { authorizeWorkspaceOperation } from "#/features/workspaces/operations/workspace-operation-context";
@@ -28,14 +25,6 @@ export async function readWorkspaceItemsOperation(
access: "read",
context: accessContext,
});
- const requestedRefs = input.requests.flatMap((request) =>
- request.mode === "ref" ? [request.ref] : [],
- );
- const referenceTargets = indexWorkspaceReferenceRecords(
- requestedRefs.length > 0 && accessContext.resolveWorkspaceReferences
- ? await accessContext.resolveWorkspaceReferences(requestedRefs)
- : [],
- );
const results = await readWorkspaceContent({
bucket: env.WORKSPACE_FILES,
getDocumentSession: (itemId) =>
@@ -49,11 +38,14 @@ export async function readWorkspaceItemsOperation(
userId: accessContext.actor.userId,
workspaceId: accessContext.workspaceId,
}),
- resolveReference: (itemId, ref) => {
- const parsedRef = parseWorkspaceReference(ref);
- const record = parsedRef ? referenceTargets.get(parsedRef) : undefined;
- return record?.location.itemId === itemId ? record.location : undefined;
- },
+ readQuizItem: (itemId) =>
+ readQuizViewer({
+ itemId,
+ userId: accessContext.actor.userId,
+ workspaceId: accessContext.workspaceId,
+ }),
+ resolveRefKey: (refKey) =>
+ getWorkspaceItemByRefKey({ refKey, workspaceId: accessContext.workspaceId }),
requests: input.requests,
workspaceId: accessContext.workspaceId,
});
@@ -65,8 +57,5 @@ export async function readWorkspaceItemsOperation(
workspaceId: accessContext.workspaceId,
});
- return {
- references: createWorkspaceReadReferences(results),
- results,
- };
+ return { results };
}
diff --git a/src/features/workspaces/operations/workspace-access-context.ts b/src/features/workspaces/operations/workspace-access-context.ts
index 0078c27a..ad3970f3 100644
--- a/src/features/workspaces/operations/workspace-access-context.ts
+++ b/src/features/workspaces/operations/workspace-access-context.ts
@@ -1,4 +1,3 @@
-import type { WorkspaceReferenceRecord } from "#/features/workspaces/locations/workspace-location";
import {
assertAccessScope,
createAccessActor,
@@ -11,27 +10,18 @@ export type WorkspaceAccessScope = (typeof workspaceAccessScopes)[number];
export interface WorkspaceAccessContext extends ScopedAccessContext {
operationId: string;
- /**
- * Resolves short refs retained in the chat transcript for reads, edits,
- * citations, and navigation. Absent outside a chat turn.
- */
- resolveWorkspaceReferences?: (refs: readonly string[]) => Promise;
workspaceId: string;
}
export function createWorkspaceAccessContext(input: {
scopes: readonly WorkspaceAccessScope[];
operationId: string;
- resolveWorkspaceReferences?: (refs: readonly string[]) => Promise;
userId: string;
workspaceId: string;
}): WorkspaceAccessContext {
return {
actor: createAccessActor(input),
operationId: input.operationId,
- ...(input.resolveWorkspaceReferences
- ? { resolveWorkspaceReferences: input.resolveWorkspaceReferences }
- : {}),
workspaceId: input.workspaceId,
};
}
diff --git a/src/features/workspaces/operations/workspace-tool-definitions.ts b/src/features/workspaces/operations/workspace-tool-definitions.ts
index 79c951f5..8f4bf8f1 100644
--- a/src/features/workspaces/operations/workspace-tool-definitions.ts
+++ b/src/features/workspaces/operations/workspace-tool-definitions.ts
@@ -144,7 +144,7 @@ export const workspaceToolDefinitions = [
name: "workspace_read_items",
access: "read",
description:
- "Read ThinkEx documents, flashcard sets, and extracted files by absolute path. Document chunks and flashcards include short, freshness-checked refs. Flashcard reads also return HTML fronts and backs plus the current user's study progress; again means missed, while hard, good, and easy mean got it. Use mode cards with a card-number range for targeted flashcard reads. Continue long documents, flashcard sets, or files with nextCursor. Use mode ref to read the exact content identified by an earlier ref; this returns elided widget source in full before editing. Files also support physical-page selections.",
+ "Read ThinkEx documents, flashcard sets, quizzes, and extracted files. Every item is an ordered list of units — document blocks, cards, questions, or physical pages — and every result names the numbered units it covered plus the total, so continue by requesting the next range: mode entries for blocks, cards, or questions; mode pages for file pages. mode start returns the first chunk. Each result carries the item's durable ref, and blocks, cards, and questions carry unit refs with a current .r_ revision — copy them exactly into edits, and cite as ref or ref/unit. Use mode ref with an address to read one unit in full; that is how elided widget source is fetched before editing. Flashcard reads include the current user's study progress (again means missed; hard, good, and easy mean got it). Quiz reads return options in user-visible order with the correct one marked, plus the user's answers and score.",
inputSchema: workspaceReadItemsInputSchema,
inputExamples: workspaceReadItemsInputExamples,
outputSchema: workspaceReadItemsOutputSchema,
@@ -192,7 +192,7 @@ export const workspaceToolDefinitions = [
name: "workspace_create_items",
access: "write",
description:
- "Create folders, documents, or flashcard sets at exact absolute paths. A slash separates folders, so use another character inside an item name. Set type and provide that branch's fields. If a path already exists, creation fails instead of renaming.",
+ "Create folders, documents, flashcard sets, or quizzes at exact absolute paths. A slash separates folders, so use another character inside an item name. Set type and provide that branch's fields. If a path already exists, creation fails instead of renaming.",
inputSchema: workspaceCreateItemsInputSchema,
inputExamples: workspaceCreateItemsInputExamples,
outputSchema: workspaceCreateItemsOutputSchema,
@@ -223,7 +223,7 @@ export const workspaceToolDefinitions = [
name: "workspace_edit_item",
access: "write",
description:
- "Edit one document or flashcard set by absolute path. Read it first, then copy the exact refs it returned. The same refs also work for citations and navigation. Flashcard edits apply immediately; document edits retain their review flow. Use workspace_link_items for item-level relationships.",
+ "Edit one document, flashcard set, or quiz by absolute path. Read it first, then copy each target's exact unit ref (like b_x7Kp2Qa9x8Lm.r_4f2a1b) from that read; the .r_ revision is how a stale edit fails loudly instead of hitting the wrong content. Flashcard and quiz edits apply immediately; document edits retain their review flow. Use workspace_link_items for item-level relationships.",
inputSchema: workspaceEditItemInputSchema,
inputExamples: workspaceEditItemInputExamples,
outputSchema: workspaceEditItemOutputSchema,
diff --git a/src/features/workspaces/operations/workspace-tool-schemas.ts b/src/features/workspaces/operations/workspace-tool-schemas.ts
index 92d2587f..c6f02e4b 100644
--- a/src/features/workspaces/operations/workspace-tool-schemas.ts
+++ b/src/features/workspaces/operations/workspace-tool-schemas.ts
@@ -17,7 +17,6 @@ import {
workspaceItemTypeSchema,
workspaceRelationKindSchema,
} from "#/features/workspaces/contracts";
-import { workspaceReferenceRecordSchema } from "#/features/workspaces/locations/workspace-location";
import {
documentAiEditSchema,
documentAiHtmlSchema,
@@ -25,6 +24,7 @@ import {
import { workspaceFileAssetKindSchema } from "#/features/workspaces/model/workspace-file";
import { flashcardEditSchema } from "#/features/workspaces/flashcards/flashcard-edits";
import { flashcardSideHtmlSchema } from "#/features/workspaces/flashcards/flashcard-content";
+import { quizEditSchema, quizQuestionInputSchema } from "#/features/workspaces/quizzes/quiz-edits";
export { workspaceReadItemsInputSchema, workspaceReadItemsOutputSchema };
@@ -42,10 +42,12 @@ const workspaceHtmlMathInstruction =
*/
const workspaceWidgetHtmlInstruction = `A widget is one interactive block inside a document. Use one when the user explicitly asks for a widget, asks for interaction or live computation, or wants a document visual that ordinary blocks cannot express. Keep ordinary content in ordinary blocks. Before authoring or editing widget source, activate the "widget-authoring" skill and follow its HTML, sandbox, layout, and editing contract. Serialize the result as …HTML-escaped fragment….`;
-export const workspaceDocumentHtmlInstruction = `Use semantic HTML with paragraphs, h1-h4, blockquotes, lists, code blocks, horizontal rules, tables, links, and standard text marks. ${workspaceHtmlMathInstruction} For checkboxes, use Item
. Documents cannot hold images: never use ![]()
or , and describe the visual in words instead. Cite workspace sources in documents exactly as in a chat reply, with Item
. Documents cannot hold images: never use ![]()
or , and describe the visual in words instead. Cite workspace sources in documents exactly as in a chat reply, with What is ATP?
", back: "The cell's main energy carrier.
" }],
},
+ {
+ type: "quiz",
+ path: "/Demo Folder/Demo Quiz",
+ questions: [
+ {
+ question: "What does ATP primarily provide to a cell?
",
+ correctAnswer: "Readily usable chemical energy
",
+ distractors: [
+ "Long-term energy storage
",
+ "Structural support for the membrane
",
+ "Genetic information for protein synthesis
",
+ ],
+ explanation:
+ "ATP transfers readily usable energy; fats store energy long-term, membranes get structure from lipids and proteins, and genetic information lives in DNA.
",
+ },
+ ],
+ },
],
});
@@ -354,7 +404,7 @@ export const workspaceEditItemInputExamples = createInputExamples<
path: "/Demo Folder/Demo Document",
edits: [
{
- ref: "wr_7Kp2Qa9x",
+ ref: "b_x7Kp2Qa9x8Lm.r_4f2a1b",
op: "replace",
html: "Updated paragraph.
",
},
@@ -365,8 +415,8 @@ export const workspaceEditItemInputExamples = createInputExamples<
path: "/Demo Folder/Demo Document",
edits: [
{
- ref: "wr_7Kp2Qa9x",
- afterRef: "wr_8Lq3Rb0y",
+ ref: "b_x7Kp2Qa9x8Lm.r_4f2a1b",
+ afterRef: "b_y8Lq3Rb0y9Mn.r_9c3d2e",
op: "move",
},
],
@@ -376,7 +426,7 @@ export const workspaceEditItemInputExamples = createInputExamples<
path: "/Demo Folder/Demo Document",
edits: [
{
- ref: "wr_7Kp2Qa9x",
+ ref: "b_x7Kp2Qa9x8Lm.r_4f2a1b",
op: "replace_text",
find: "gravity = 9.8",
replace: "gravity = 3.7",
@@ -389,11 +439,24 @@ export const workspaceEditItemInputExamples = createInputExamples<
edits: [
{
op: "update",
- ref: "wr_7Kp2Qa9x",
+ ref: "c_9xKp2Qab.r_4f2a1b",
back: "The cell's main energy carrier.
",
},
],
},
+ {
+ type: "quiz",
+ path: "/Demo Folder/Demo Quiz",
+ edits: [
+ {
+ op: "replace_text",
+ ref: "q_8Lq3Rb0y.r_9c3d2e",
+ field: "options",
+ find: "Long-term energy storage",
+ replace: "Long-term energy reserves",
+ },
+ ],
+ },
);
export const workspaceLinkItemsInputExamples = createInputExamples<
@@ -424,13 +487,12 @@ export const workspaceListItemsOutputSchema = z.object({
export const workspaceCreateItemsOutputSchema = createWorkspaceItemsResultSchema({
itemSchema: workspacePathItemSchema.extend({
itemId: z.string().min(1),
- type: z.enum(["document", "flashcard", "folder"]),
+ ref: z.string().min(1).describe("The item's durable address for citations and reads."),
+ type: z.enum(["document", "flashcard", "folder", "quiz"]),
}),
failureSchema: createFailureSchema(createWorkspaceItemsFailureCodes).extend({
detail: z.string().optional().describe("Why this item was refused, when the reason is known."),
}),
-}).extend({
- references: z.array(workspaceReferenceRecordSchema),
});
export const workspaceDeleteItemsOutputSchema = createWorkspaceItemsResultSchema({
@@ -456,7 +518,7 @@ export const workspaceEditItemOutputSchema = z.object({
path: workspacePathSchema,
applied: z.number().int().min(0),
itemId: z.string().optional(),
- itemType: z.enum(["document", "flashcard"]).optional(),
+ itemType: z.enum(["document", "flashcard", "quiz"]).optional(),
lineChanges: z
.object({ added: z.number().int().min(0), removed: z.number().int().min(0) })
.optional(),
diff --git a/src/features/workspaces/operations/workspace-tool-surface.test.ts b/src/features/workspaces/operations/workspace-tool-surface.test.ts
index 7ad877ab..e9bae42a 100644
--- a/src/features/workspaces/operations/workspace-tool-surface.test.ts
+++ b/src/features/workspaces/operations/workspace-tool-surface.test.ts
@@ -45,10 +45,10 @@ describe("workspace tool surface", () => {
}
it("gives documents and flashcards the same edit verbs and ref protocol", () => {
- const documentRef = "wr_AAAAAAAA";
- const otherDocumentRef = "wr_BBBBBBBB";
- const flashcardRef = "wr_CCCCCCCC";
- const otherFlashcardRef = "wr_DDDDDDDD";
+ const documentRef = "b_x7Kp2Qa9x8Lm.r_4f2a1b";
+ const otherDocumentRef = "b_y8Lq3Rb0y9Mn.r_9c3d2e";
+ const flashcardRef = "c_9xKp2Qab.r_4f2a1b";
+ const otherFlashcardRef = "c_8Lq3Rb0y.r_9c3d2e";
const sharedVerbs = [
"insert_before",
"insert_after",
diff --git a/src/lib/binary.ts b/src/lib/binary.ts
index f04ffe7b..aab904fe 100644
--- a/src/lib/binary.ts
+++ b/src/lib/binary.ts
@@ -21,10 +21,6 @@ export function decodeBase64Url(value: string) {
return Uint8Array.from(atob(padded), (character) => character.charCodeAt(0));
}
-export function encodeBase64UrlText(value: string) {
- return encodeBase64Url(textEncoder.encode(value));
-}
-
export function decodeBase64UrlText(value: string) {
return textDecoder.decode(decodeBase64Url(value));
}
From ffd73aa5481dd90fbecf81d357c68b6891a92c25 Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Sat, 15 Aug 2026 01:34:51 -0400
Subject: [PATCH 04/14] fix(workspaces): apply fresh-eyes review findings
Entry-range failures carry their real codes and a recovery message,
the range description no longer teaches comma lists to documents, and
the simplification pass lands: one shared Fisher-Yates, alias chains
and the leftover adapter factory removed, dead userId branches and
unused exports deleted.
Part 4 of the stacked series; tree is byte-identical to the verified
add-quiz-item-type branch.
---
.../ai/workspace-tool-result-adapters.ts | 55 +++++++------------
.../workspaces/content/entry-rich-text.ts | 10 +---
.../content/workspace-content-contract.ts | 2 +-
.../content/workspace-content-reader.ts | 34 ++++++++++--
.../flashcards/flashcard-content.ts | 16 ++----
.../workspaces/flashcards/flashcard-edits.ts | 21 ++++---
.../flashcards/flashcard-persistence.ts | 10 +---
.../flashcards/flashcard-study-session.ts | 9 +--
.../workspace-tool-surface.test.ts.snap | 2 +-
.../operations/workspace-tool-schemas.ts | 6 +-
.../workspaces/quizzes/quiz-content.ts | 30 +++-------
.../workspaces/quizzes/quiz-edits.test.ts | 8 +--
src/features/workspaces/quizzes/quiz-edits.ts | 23 ++++----
.../workspaces/quizzes/quiz-persistence.ts | 6 +-
.../workspaces/quizzes/quiz-study-session.ts | 9 +--
src/lib/shuffle.ts | 10 ++++
16 files changed, 108 insertions(+), 143 deletions(-)
create mode 100644 src/lib/shuffle.ts
diff --git a/src/features/workspaces/ai/workspace-tool-result-adapters.ts b/src/features/workspaces/ai/workspace-tool-result-adapters.ts
index 930c048c..043426a8 100644
--- a/src/features/workspaces/ai/workspace-tool-result-adapters.ts
+++ b/src/features/workspaces/ai/workspace-tool-result-adapters.ts
@@ -1,5 +1,4 @@
import type { JSONValue } from "ai";
-import { z } from "zod";
import { workspaceReadItemsOutputSchema } from "#/features/workspaces/content/workspace-content-contract";
import { createWorkspaceReadItemsModelOutput } from "#/features/workspaces/content/workspace-read-model-output";
@@ -13,41 +12,27 @@ import {
* the model needs. Addresses are already self-describing, so projection is
* only ever subtraction: internal item ids and app-side bookkeeping.
*/
-function defineWorkspaceToolResultAdapter(input: {
- outputSchema: TSchema;
- projectOutput: (output: z.output) => unknown;
-}) {
- return {
- projectOutput: (output: unknown) => {
- return input.projectOutput(input.outputSchema.parse(output)) as JSONValue;
- },
- };
-}
-
-const workspaceReadItemsResultAdapter = defineWorkspaceToolResultAdapter({
- outputSchema: workspaceReadItemsOutputSchema,
- projectOutput: createWorkspaceReadItemsModelOutput,
-});
-
-const workspaceCreateItemsResultAdapter = defineWorkspaceToolResultAdapter({
- outputSchema: workspaceCreateItemsOutputSchema,
- projectOutput: (output) => ({
- failed: output.failed,
- items: output.items.map(({ itemId: _itemId, ...item }) => item),
- }),
-});
-
-// The operation output also carries the durable item id used by the app's
-// review controls. Keep the model-facing receipt limited to actionable counts.
-const workspaceEditItemResultAdapter = defineWorkspaceToolResultAdapter({
- outputSchema: workspaceEditItemOutputSchema,
- projectOutput: ({ applied, failed, path }) => ({ applied, failed, path }),
-});
-
const workspaceToolResultAdapters = {
- workspace_create_items: workspaceCreateItemsResultAdapter,
- workspace_edit_item: workspaceEditItemResultAdapter,
- workspace_read_items: workspaceReadItemsResultAdapter,
+ workspace_create_items: {
+ projectOutput: (output: unknown): JSONValue => {
+ const { failed, items } = workspaceCreateItemsOutputSchema.parse(output);
+ return { failed, items: items.map(({ itemId: _itemId, ...item }) => item) } as JSONValue;
+ },
+ },
+ // The operation output also carries the durable item id used by the app's
+ // review controls. Keep the model-facing receipt limited to actionable counts.
+ workspace_edit_item: {
+ projectOutput: (output: unknown): JSONValue => {
+ const { applied, failed, path } = workspaceEditItemOutputSchema.parse(output);
+ return { applied, failed, path } as JSONValue;
+ },
+ },
+ workspace_read_items: {
+ projectOutput: (output: unknown): JSONValue =>
+ createWorkspaceReadItemsModelOutput(
+ workspaceReadItemsOutputSchema.parse(output),
+ ) as JSONValue,
+ },
} as const;
export function getWorkspaceToolResultAdapter(name: string) {
diff --git a/src/features/workspaces/content/entry-rich-text.ts b/src/features/workspaces/content/entry-rich-text.ts
index e89f6e1d..13c18137 100644
--- a/src/features/workspaces/content/entry-rich-text.ts
+++ b/src/features/workspaces/content/entry-rich-text.ts
@@ -1,9 +1,6 @@
import { z } from "zod";
-import {
- parseDocumentAiHtml,
- serializeTiptapDocumentToHtml,
-} from "#/features/workspaces/documents/document-ai-html";
+import { parseDocumentAiHtml } from "#/features/workspaces/documents/document-ai-html";
import {
coerceTiptapDocumentProjection,
type TiptapDocumentJson,
@@ -49,7 +46,6 @@ export function createEntryRichTextParser(messages: EntryRichTextMessages) {
}
return {
- assertEntryRichText,
parseEntryRichTextHtml(html: string): TiptapDocumentJson {
const document = parseDocumentAiHtml(html);
assertEntryRichText(document);
@@ -66,10 +62,6 @@ export function createEntryRichTextParser(messages: EntryRichTextMessages) {
};
}
-export function serializeEntryRichTextToHtml(entry: TiptapDocumentJson) {
- return serializeTiptapDocumentToHtml(entry);
-}
-
function visitRichTextValue(value: unknown, messages: EntryRichTextMessages) {
if (Array.isArray(value)) {
for (const entry of value) visitRichTextValue(entry, messages);
diff --git a/src/features/workspaces/content/workspace-content-contract.ts b/src/features/workspaces/content/workspace-content-contract.ts
index 95d204d9..e4f3afb6 100644
--- a/src/features/workspaces/content/workspace-content-contract.ts
+++ b/src/features/workspaces/content/workspace-content-contract.ts
@@ -35,7 +35,7 @@ const workspacePageRangeSchema = workspaceNumberRangeSchema.describe(
"Up to 20 physical pages from an extracted file, like 1, 3, 5-7, or 1,4-6.",
);
const workspaceEntryRangeSchema = workspaceNumberRangeSchema.describe(
- "Up to 20 entry numbers — document blocks, flashcards, or quiz questions — like 1, 3, 5-7, or 1,4-6.",
+ "Up to 20 entry numbers. Flashcards and quiz questions take lists like 1, 3, 5-7; document blocks take one contiguous range like 5-12.",
);
/**
diff --git a/src/features/workspaces/content/workspace-content-reader.ts b/src/features/workspaces/content/workspace-content-reader.ts
index 6119389a..2f965bd5 100644
--- a/src/features/workspaces/content/workspace-content-reader.ts
+++ b/src/features/workspaces/content/workspace-content-reader.ts
@@ -266,7 +266,14 @@ async function readFlashcards(
request: input.request,
targetEntryId: targetCardId,
});
- if (!selection.ok) return { code: selection.code, path: input.path, status: "failed" };
+ if (!selection.ok) {
+ return {
+ code: selection.code,
+ ...(selection.message ? { message: selection.message } : {}),
+ path: input.path,
+ status: "failed",
+ };
+ }
return {
cards: await Promise.all(
@@ -320,7 +327,14 @@ async function readQuiz(
request: input.request,
targetEntryId: targetQuestionId,
});
- if (!selection.ok) return { code: selection.code, path: input.path, status: "failed" };
+ if (!selection.ok) {
+ return {
+ code: selection.code,
+ ...(selection.message ? { message: selection.message } : {}),
+ path: input.path,
+ status: "failed",
+ };
+ }
return {
format: "html",
@@ -364,7 +378,15 @@ async function readQuiz(
type OrderedEntrySelection =
| { ok: true; selected: T[]; returned: number[] }
- | { ok: false; code: "invalid_selection" | "ref_not_found" };
+ | {
+ ok: false;
+ code:
+ | "invalid_selection"
+ | "page_range_out_of_range"
+ | "page_selection_too_large"
+ | "ref_not_found";
+ message?: string;
+ };
/**
* Shared selection for structured items: one targeted entry from an address,
@@ -391,7 +413,11 @@ function selectOrderedEntries(input: {
returned = parseWorkspacePageRange(request.range, entries.length);
} catch (error) {
if (error instanceof WorkspacePageSelectionError) {
- return { ok: false, code: "invalid_selection" };
+ return {
+ ok: false,
+ code: error.code,
+ message: `The item has ${entries.length} entries; request up to 20 of them per read.`,
+ };
}
throw error;
}
diff --git a/src/features/workspaces/flashcards/flashcard-content.ts b/src/features/workspaces/flashcards/flashcard-content.ts
index 4914f36f..aa404eff 100644
--- a/src/features/workspaces/flashcards/flashcard-content.ts
+++ b/src/features/workspaces/flashcards/flashcard-content.ts
@@ -1,8 +1,5 @@
-import {
- createEntryRichTextParser,
- entryRichTextHtmlSchema,
- serializeEntryRichTextToHtml,
-} from "#/features/workspaces/content/entry-rich-text";
+import { createEntryRichTextParser } from "#/features/workspaces/content/entry-rich-text";
+import { serializeTiptapDocumentToHtml } from "#/features/workspaces/documents/document-ai-html";
import type { TiptapDocumentJson } from "#/features/workspaces/documents/tiptap-document";
import {
createWorkspaceEntryId,
@@ -12,7 +9,6 @@ import { sha256Base64UrlText } from "#/lib/binary";
import { isRecord } from "#/lib/record";
export const FLASHCARD_SET_VERSION = 1;
-export const flashcardSideHtmlSchema = entryRichTextHtmlSchema;
const flashcardIdSchema = workspaceEntryIdSchema;
export interface Flashcard {
@@ -93,10 +89,6 @@ export function stringifyFlashcardSetContent(content: FlashcardSetContent) {
return `${JSON.stringify(content)}\n`;
}
-export function serializeFlashcardSideToHtml(side: TiptapDocumentJson) {
- return serializeEntryRichTextToHtml(side);
-}
-
export async function createFlashcardRevision(card: Flashcard) {
return (await sha256Base64UrlText(JSON.stringify({ front: card.front, back: card.back }))).slice(
0,
@@ -107,7 +99,7 @@ export async function createFlashcardRevision(card: Flashcard) {
export function serializeFlashcardSetToHtml(content: FlashcardSetContent): FlashcardHtmlCard[] {
return content.cards.map((card) => ({
id: card.id,
- front: serializeFlashcardSideToHtml(card.front),
- back: serializeFlashcardSideToHtml(card.back),
+ front: serializeTiptapDocumentToHtml(card.front),
+ back: serializeTiptapDocumentToHtml(card.back),
}));
}
diff --git a/src/features/workspaces/flashcards/flashcard-edits.ts b/src/features/workspaces/flashcards/flashcard-edits.ts
index e96aa455..ba7be66e 100644
--- a/src/features/workspaces/flashcards/flashcard-edits.ts
+++ b/src/features/workspaces/flashcards/flashcard-edits.ts
@@ -8,12 +8,12 @@ import {
import { replaceUniqueText } from "#/features/workspaces/content/replace-unique-text";
import {
createFlashcardRevision,
- flashcardSideHtmlSchema,
parseFlashcardSideHtml,
- serializeFlashcardSideToHtml,
type Flashcard,
type FlashcardSetContent,
} from "#/features/workspaces/flashcards/flashcard-content";
+import { entryRichTextHtmlSchema } from "#/features/workspaces/content/entry-rich-text";
+import { serializeTiptapDocumentToHtml } from "#/features/workspaces/documents/document-ai-html";
import {
createWorkspaceEntryId,
workspaceUnitRefInputSchema,
@@ -25,15 +25,15 @@ export const flashcardEditSchema = z.union([
z.strictObject({
op: z.enum(["insert_before", "insert_after"]),
ref: workspaceUnitRefInputSchema,
- front: flashcardSideHtmlSchema,
- back: flashcardSideHtmlSchema,
+ front: entryRichTextHtmlSchema,
+ back: entryRichTextHtmlSchema,
}),
z
.strictObject({
op: z.literal("update"),
ref: workspaceUnitRefInputSchema,
- front: flashcardSideHtmlSchema.optional(),
- back: flashcardSideHtmlSchema.optional(),
+ front: entryRichTextHtmlSchema.optional(),
+ back: entryRichTextHtmlSchema.optional(),
})
.refine((value) => value.front !== undefined || value.back !== undefined, {
message: "Provide a new front or back.",
@@ -41,8 +41,8 @@ export const flashcardEditSchema = z.union([
z.strictObject({
op: z.literal("replace"),
ref: workspaceUnitRefInputSchema,
- front: flashcardSideHtmlSchema,
- back: flashcardSideHtmlSchema,
+ front: entryRichTextHtmlSchema,
+ back: entryRichTextHtmlSchema,
}),
z.strictObject({
op: z.literal("replace_text"),
@@ -70,12 +70,11 @@ export const flashcardEditSchema = z.union([
]);
export type FlashcardEdit = z.output;
-export type FlashcardEditTarget = OrderedEntryEditTarget;
export async function applyFlashcardEdits(
content: FlashcardSetContent,
edits: FlashcardEdit[],
- targets: ReadonlyMap,
+ targets: ReadonlyMap,
) {
const result = await applyOrderedEntryEdits({
entries: content.cards,
@@ -122,7 +121,7 @@ function reviseCard(card: Flashcard, edit: FlashcardEdit): Flashcard {
}
if (edit.op === "replace_text") {
const replaced = replaceUniqueText(
- serializeFlashcardSideToHtml(card[edit.side]),
+ serializeTiptapDocumentToHtml(card[edit.side]),
edit.find,
edit.replace,
);
diff --git a/src/features/workspaces/flashcards/flashcard-persistence.ts b/src/features/workspaces/flashcards/flashcard-persistence.ts
index ceb80dd5..0c17c9d3 100644
--- a/src/features/workspaces/flashcards/flashcard-persistence.ts
+++ b/src/features/workspaces/flashcards/flashcard-persistence.ts
@@ -14,17 +14,9 @@ import {
withWorkspaceTransaction,
} from "#/features/workspaces/persistence/workspace-postgres-support";
import { notifyWorkspaceRoom } from "#/features/workspaces/realtime/workspace-room-notifier";
-import { assertCanReadWorkspace } from "#/features/workspaces/server/permissions";
-export async function readFlashcardSet(input: {
- itemId: string;
- workspaceId: string;
- userId?: string;
-}) {
+export async function readFlashcardSet(input: { itemId: string; workspaceId: string }) {
return await withDb(async (db) => {
- if (input.userId) {
- await assertCanReadWorkspace(db, { workspaceId: input.workspaceId, userId: input.userId });
- }
const [row] = await db
.select({ content: workspaceItemContents.content })
.from(workspaceItems)
diff --git a/src/features/workspaces/flashcards/flashcard-study-session.ts b/src/features/workspaces/flashcards/flashcard-study-session.ts
index a6479147..3917da0d 100644
--- a/src/features/workspaces/flashcards/flashcard-study-session.ts
+++ b/src/features/workspaces/flashcards/flashcard-study-session.ts
@@ -4,6 +4,7 @@ import type {
FlashcardStudyRating,
FlashcardStudyState,
} from "#/features/workspaces/flashcards/flashcard-study-state";
+import { shuffleInPlace } from "#/lib/shuffle";
export type FlashcardStudyMode = "all" | "missed";
@@ -46,11 +47,5 @@ export function createFlashcardStudyQueue(
}
}
- if (!input.shuffled) return cardIds;
-
- for (let index = cardIds.length - 1; index > 0; index -= 1) {
- const swapIndex = Math.floor(random() * (index + 1));
- [cardIds[index], cardIds[swapIndex]] = [cardIds[swapIndex]!, cardIds[index]!];
- }
- return cardIds;
+ return input.shuffled ? shuffleInPlace(cardIds, random) : cardIds;
}
diff --git a/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap b/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap
index 5f94c410..916c1cb2 100644
--- a/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap
+++ b/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap
@@ -1157,7 +1157,7 @@ exports[`workspace tool surface > workspace_read_items input schema is stable 1`
"type": "string",
},
"range": {
- "description": "Up to 20 entry numbers — document blocks, flashcards, or quiz questions — like 1, 3, 5-7, or 1,4-6.",
+ "description": "Up to 20 entry numbers. Flashcards and quiz questions take lists like 1, 3, 5-7; document blocks take one contiguous range like 5-12.",
"minLength": 1,
"pattern": "^\\d+(?:\\s*-\\s*\\d+)?(?:\\s*,\\s*\\d+(?:\\s*-\\s*\\d+)?)*$",
"type": "string",
diff --git a/src/features/workspaces/operations/workspace-tool-schemas.ts b/src/features/workspaces/operations/workspace-tool-schemas.ts
index c6f02e4b..249a88d6 100644
--- a/src/features/workspaces/operations/workspace-tool-schemas.ts
+++ b/src/features/workspaces/operations/workspace-tool-schemas.ts
@@ -23,8 +23,8 @@ import {
} from "#/features/workspaces/documents/document-ai-edits";
import { workspaceFileAssetKindSchema } from "#/features/workspaces/model/workspace-file";
import { flashcardEditSchema } from "#/features/workspaces/flashcards/flashcard-edits";
-import { flashcardSideHtmlSchema } from "#/features/workspaces/flashcards/flashcard-content";
import { quizEditSchema, quizQuestionInputSchema } from "#/features/workspaces/quizzes/quiz-edits";
+import { entryRichTextHtmlSchema } from "#/features/workspaces/content/entry-rich-text";
export { workspaceReadItemsInputSchema, workspaceReadItemsOutputSchema };
@@ -240,8 +240,8 @@ export const workspaceCreateItemsInputSchema = z.object({
cards: z
.array(
z.object({
- front: flashcardSideHtmlSchema.describe("HTML shown before the card flips."),
- back: flashcardSideHtmlSchema.describe("HTML shown after the card flips."),
+ front: entryRichTextHtmlSchema.describe("HTML shown before the card flips."),
+ back: entryRichTextHtmlSchema.describe("HTML shown after the card flips."),
}),
)
.min(1)
diff --git a/src/features/workspaces/quizzes/quiz-content.ts b/src/features/workspaces/quizzes/quiz-content.ts
index e8b9d3ac..f78fa9f9 100644
--- a/src/features/workspaces/quizzes/quiz-content.ts
+++ b/src/features/workspaces/quizzes/quiz-content.ts
@@ -1,8 +1,5 @@
-import {
- createEntryRichTextParser,
- entryRichTextHtmlSchema,
- serializeEntryRichTextToHtml,
-} from "#/features/workspaces/content/entry-rich-text";
+import { createEntryRichTextParser } from "#/features/workspaces/content/entry-rich-text";
+import { serializeTiptapDocumentToHtml } from "#/features/workspaces/documents/document-ai-html";
import type { TiptapDocumentJson } from "#/features/workspaces/documents/tiptap-document";
import {
createWorkspaceEntryId,
@@ -10,9 +7,9 @@ import {
} from "#/features/workspaces/locations/workspace-location";
import { sha256Base64UrlText } from "#/lib/binary";
import { isRecord } from "#/lib/record";
+import { shuffleInPlace } from "#/lib/shuffle";
export const QUIZ_SET_VERSION = 1;
-export const quizRichTextHtmlSchema = entryRichTextHtmlSchema;
const quizIdSchema = workspaceEntryIdSchema;
export const QUIZ_QUESTION_MIN_DISTRACTORS = 1;
@@ -182,10 +179,6 @@ export function stringifyQuizSetContent(content: QuizSetContent) {
return `${JSON.stringify(content)}\n`;
}
-export function serializeQuizRichTextToHtml(value: TiptapDocumentJson) {
- return serializeEntryRichTextToHtml(value);
-}
-
export async function createQuizQuestionRevision(question: QuizQuestion) {
return (
await sha256Base64UrlText(
@@ -209,32 +202,23 @@ export interface QuizHtmlQuestion {
export function serializeQuizSetToHtml(content: QuizSetContent): QuizHtmlQuestion[] {
return content.questions.map((question) => ({
id: question.id,
- question: serializeQuizRichTextToHtml(question.question),
+ question: serializeTiptapDocumentToHtml(question.question),
options: question.options.map((option) => ({
id: option.id,
- text: serializeQuizRichTextToHtml(option.text),
+ text: serializeTiptapDocumentToHtml(option.text),
correct: option.id === question.correctOptionId,
})),
- explanation: serializeQuizRichTextToHtml(question.explanation),
+ explanation: serializeTiptapDocumentToHtml(question.explanation),
}));
}
function assertDistinctOptions(options: QuizOption[]) {
const seen = new Set();
for (const option of options) {
- const key = serializeEntryRichTextToHtml(option.text);
+ const key = serializeTiptapDocumentToHtml(option.text);
if (seen.has(key)) {
throw new Error("Every option in a question must be distinct.");
}
seen.add(key);
}
}
-
-function shuffleInPlace(values: T[]) {
- for (let i = values.length - 1; i > 0; i--) {
- const j = Math.floor(Math.random() * (i + 1));
- const a = values[i]!;
- values[i] = values[j]!;
- values[j] = a;
- }
-}
diff --git a/src/features/workspaces/quizzes/quiz-edits.test.ts b/src/features/workspaces/quizzes/quiz-edits.test.ts
index 433e852a..5b4f4593 100644
--- a/src/features/workspaces/quizzes/quiz-edits.test.ts
+++ b/src/features/workspaces/quizzes/quiz-edits.test.ts
@@ -3,9 +3,9 @@ import { describe, expect, it } from "vitest";
import {
createQuizQuestionRevision,
createQuizSetFromInputs,
- serializeQuizRichTextToHtml,
type QuizQuestion,
} from "#/features/workspaces/quizzes/quiz-content";
+import { serializeTiptapDocumentToHtml } from "#/features/workspaces/documents/document-ai-html";
import { applyQuizEdits, quizEditSchema } from "#/features/workspaces/quizzes/quiz-edits";
const firstQuestion = {
@@ -50,11 +50,11 @@ describe("applyQuizEdits", () => {
expect(result.applied).toBe(5);
expect(result.content.questions).toHaveLength(3);
const revisedSecond = result.content.questions.find((entry) => entry.id === second!.id)!;
- expect(serializeQuizRichTextToHtml(revisedSecond.explanation)).toBe(
+ expect(serializeTiptapDocumentToHtml(revisedSecond.explanation)).toBe(
"Updated explanation.
",
);
expect(
- revisedSecond.options.map((option) => serializeQuizRichTextToHtml(option.text)),
+ revisedSecond.options.map((option) => serializeTiptapDocumentToHtml(option.text)),
).toContain("The mitochondria
");
// replace keeps the id so citations to the question survive re-authoring.
expect(result.content.questions.some((entry) => entry.id === first!.id)).toBe(true);
@@ -82,7 +82,7 @@ describe("applyQuizEdits", () => {
expect(result.failed).toEqual([]);
const revised = result.content.questions[0]!;
const correct = revised.options.find((option) => option.id === revised.correctOptionId)!;
- expect(serializeQuizRichTextToHtml(correct.text)).toBe("Readily usable energy
");
+ expect(serializeTiptapDocumentToHtml(correct.text)).toBe("Readily usable energy
");
});
it("rejects option fixes that match more than one option", async () => {
diff --git a/src/features/workspaces/quizzes/quiz-edits.ts b/src/features/workspaces/quizzes/quiz-edits.ts
index ccf0c035..d111162e 100644
--- a/src/features/workspaces/quizzes/quiz-edits.ts
+++ b/src/features/workspaces/quizzes/quiz-edits.ts
@@ -10,30 +10,30 @@ import {
createQuizQuestionRevision,
materializeQuizQuestion,
parseQuizRichTextHtml,
- quizRichTextHtmlSchema,
QUIZ_QUESTION_MAX_DISTRACTORS,
QUIZ_QUESTION_MIN_DISTRACTORS,
- serializeQuizRichTextToHtml,
type QuizQuestion,
type QuizSetContent,
} from "#/features/workspaces/quizzes/quiz-content";
+import { entryRichTextHtmlSchema } from "#/features/workspaces/content/entry-rich-text";
+import { serializeTiptapDocumentToHtml } from "#/features/workspaces/documents/document-ai-html";
import { workspaceUnitRefInputSchema } from "#/features/workspaces/locations/workspace-location";
const editTextSchema = z.string().max(8_000);
const authoredQuestionFields = {
- question: quizRichTextHtmlSchema.describe("HTML question stem."),
- correctAnswer: quizRichTextHtmlSchema.describe(
+ question: entryRichTextHtmlSchema.describe("HTML question stem."),
+ correctAnswer: entryRichTextHtmlSchema.describe(
"HTML for the single correct option. Never mark it in the stem; its final position is shuffled server-side.",
),
distractors: z
- .array(quizRichTextHtmlSchema)
+ .array(entryRichTextHtmlSchema)
.min(QUIZ_QUESTION_MIN_DISTRACTORS)
.max(QUIZ_QUESTION_MAX_DISTRACTORS)
.describe(
"HTML for each incorrect option: strictly wrong, plausible, and grounded in a specific misconception. Use 3 for a standard question, 1 for true/false.",
),
- explanation: quizRichTextHtmlSchema.describe(
+ explanation: entryRichTextHtmlSchema.describe(
"Short HTML explanation of why the correct answer is right, touching on why the others are not.",
),
};
@@ -51,8 +51,8 @@ export const quizEditSchema = z.union([
.strictObject({
op: z.literal("update"),
ref: workspaceUnitRefInputSchema,
- question: quizRichTextHtmlSchema.optional().describe("New HTML question stem."),
- explanation: quizRichTextHtmlSchema.optional().describe("New HTML explanation."),
+ question: entryRichTextHtmlSchema.optional().describe("New HTML question stem."),
+ explanation: entryRichTextHtmlSchema.optional().describe("New HTML explanation."),
})
.refine((value) => value.question !== undefined || value.explanation !== undefined, {
message: "Provide a new question or explanation.",
@@ -90,12 +90,11 @@ export const quizEditSchema = z.union([
]);
export type QuizEdit = z.output;
-export type QuizEditTarget = OrderedEntryEditTarget;
export async function applyQuizEdits(
content: QuizSetContent,
edits: QuizEdit[],
- targets: ReadonlyMap,
+ targets: ReadonlyMap,
) {
const result = await applyOrderedEntryEdits({
entries: content.questions,
@@ -152,7 +151,7 @@ function replaceQuestionText(
let matchedTwiceInOne = false;
for (const [index, option] of question.options.entries()) {
const replaced = replaceUniqueText(
- serializeQuizRichTextToHtml(option.text),
+ serializeTiptapDocumentToHtml(option.text),
edit.find,
edit.replace,
);
@@ -181,7 +180,7 @@ function replaceQuestionText(
}
const replaced = replaceUniqueText(
- serializeQuizRichTextToHtml(question[edit.field]),
+ serializeTiptapDocumentToHtml(question[edit.field]),
edit.find,
edit.replace,
);
diff --git a/src/features/workspaces/quizzes/quiz-persistence.ts b/src/features/workspaces/quizzes/quiz-persistence.ts
index 1932be9d..dd54bb89 100644
--- a/src/features/workspaces/quizzes/quiz-persistence.ts
+++ b/src/features/workspaces/quizzes/quiz-persistence.ts
@@ -14,13 +14,9 @@ import {
withWorkspaceTransaction,
} from "#/features/workspaces/persistence/workspace-postgres-support";
import { notifyWorkspaceRoom } from "#/features/workspaces/realtime/workspace-room-notifier";
-import { assertCanReadWorkspace } from "#/features/workspaces/server/permissions";
-export async function readQuizSet(input: { itemId: string; workspaceId: string; userId?: string }) {
+export async function readQuizSet(input: { itemId: string; workspaceId: string }) {
return await withDb(async (db) => {
- if (input.userId) {
- await assertCanReadWorkspace(db, { workspaceId: input.workspaceId, userId: input.userId });
- }
const [row] = await db
.select({ content: workspaceItemContents.content })
.from(workspaceItems)
diff --git a/src/features/workspaces/quizzes/quiz-study-session.ts b/src/features/workspaces/quizzes/quiz-study-session.ts
index bf752930..8cb4c27f 100644
--- a/src/features/workspaces/quizzes/quiz-study-session.ts
+++ b/src/features/workspaces/quizzes/quiz-study-session.ts
@@ -4,6 +4,7 @@ import {
type QuizStudyProgress,
type QuizStudyState,
} from "#/features/workspaces/quizzes/quiz-study-state";
+import { shuffleInPlace } from "#/lib/shuffle";
export type QuizStudyMode = "all" | "missed";
@@ -26,13 +27,7 @@ export function createQuizStudyQueue(
}
}
- if (!input.shuffled) return questionIds;
-
- for (let index = questionIds.length - 1; index > 0; index -= 1) {
- const swapIndex = Math.floor(random() * (index + 1));
- [questionIds[index], questionIds[swapIndex]] = [questionIds[swapIndex]!, questionIds[index]!];
- }
- return questionIds;
+ return input.shuffled ? shuffleInPlace(questionIds, random) : questionIds;
}
/** What the AI's live view context says about the open quiz. */
diff --git a/src/lib/shuffle.ts b/src/lib/shuffle.ts
new file mode 100644
index 00000000..a94c31cf
--- /dev/null
+++ b/src/lib/shuffle.ts
@@ -0,0 +1,10 @@
+/** Fisher–Yates, in place. Pass a seeded `random` for deterministic tests. */
+export function shuffleInPlace(values: T[], random: () => number = Math.random) {
+ for (let index = values.length - 1; index > 0; index -= 1) {
+ const swapIndex = Math.floor(random() * (index + 1));
+ const value = values[index]!;
+ values[index] = values[swapIndex]!;
+ values[swapIndex] = value;
+ }
+ return values;
+}
From 12fc7e66d15dcbcb93dd9124de0e62b42187da5f Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Sat, 15 Aug 2026 14:56:21 -0400
Subject: [PATCH 05/14] refactor(workspaces): share study session chrome
between viewers
The flashcard and quiz viewers each carried their own copy of the same
pieces: a read-only Tiptap render, the amber "ask AI" button, the
prev/next arrows, and the progress strip. Same look, four chances to
drift.
Extracts them into components/study: StudyRichText, StudyAiActionButton,
StudyNavButton, and StudyProgressStrip, whose segments now carry a tone
so each item type maps its own state onto one strip.
---
.../components/flashcards/FlashcardViewer.tsx | 175 +++++-------------
.../components/study/StudyProgressStrip.tsx | 68 +++++++
.../components/study/StudyRichText.tsx | 36 ++++
.../components/study/StudySessionControls.tsx | 66 +++++++
4 files changed, 214 insertions(+), 131 deletions(-)
create mode 100644 src/features/workspaces/components/study/StudyProgressStrip.tsx
create mode 100644 src/features/workspaces/components/study/StudyRichText.tsx
create mode 100644 src/features/workspaces/components/study/StudySessionControls.tsx
diff --git a/src/features/workspaces/components/flashcards/FlashcardViewer.tsx b/src/features/workspaces/components/flashcards/FlashcardViewer.tsx
index d7fbaf52..efe4f5e1 100644
--- a/src/features/workspaces/components/flashcards/FlashcardViewer.tsx
+++ b/src/features/workspaces/components/flashcards/FlashcardViewer.tsx
@@ -1,16 +1,22 @@
import { useQuery } from "@tanstack/react-query";
-import type { JSONContent } from "@tiptap/core";
-import { EditorContent, useEditor } from "@tiptap/react";
-import { Check, ChevronLeft, ChevronRight, Lightbulb, X } from "lucide-react";
+import { Check, X } from "lucide-react";
import { domAnimation, LazyMotion, m, MotionConfig } from "motion/react";
import { type ReactNode, useCallback, useEffect, useMemo, useState } from "react";
import { Button } from "#/components/ui/button";
import { Skeleton } from "#/components/ui/skeleton";
import { sendComposerPrompt } from "#/features/workspaces/composer/workspace-composer-actions";
+import {
+ StudyProgressStrip,
+ type StudyProgressTone,
+} from "#/features/workspaces/components/study/StudyProgressStrip";
+import { StudyRichText } from "#/features/workspaces/components/study/StudyRichText";
+import {
+ StudyAiActionButton,
+ StudyNavButton,
+} from "#/features/workspaces/components/study/StudySessionControls";
import { StudyToolbar } from "#/features/workspaces/components/study/StudyToolbar";
import { useWorkspaceItemToolbar } from "#/features/workspaces/components/WorkspaceItemToolbarSlot";
-import { getTiptapDocumentBaseExtensions } from "#/features/workspaces/documents/tiptap-extensions";
import type { TiptapDocumentJson } from "#/features/workspaces/documents/tiptap-document";
import {
flashcardViewerQueryOptions,
@@ -573,7 +579,8 @@ function FlashcardStudySurface({
label="Front"
content={currentCard.front}
action={
-
sendComposerPrompt(
@@ -590,7 +597,8 @@ function FlashcardStudySurface({
label="Back"
content={currentCard.back}
action={
-
sendComposerPrompt(
@@ -607,30 +615,28 @@ function FlashcardStudySurface({
- {
+ const { label, tone } = describeFlashcardRating(
+ studyState.cards[card.id]?.lastRating,
+ );
+ return { id: card.id, label: `Card ${index + 1}: ${label}`, tone };
+ })}
/>
{gotItCount + missedCount} reviewed
-
+ />
-
+ />
{currentIndex + 1} of {studyCards.length}
@@ -687,66 +688,6 @@ function FlashcardStudySurface({
);
}
-function FlashcardStatusStrip({
- cards,
- currentIndex,
- gotItCount,
- missedCount,
- onSelect,
- reviewsByCardId,
-}: {
- cards: Flashcard[];
- currentIndex: number;
- gotItCount: number;
- missedCount: number;
- onSelect: (index: number) => void;
- reviewsByCardId: FlashcardStudyState["cards"];
-}) {
- const unseenCount = cards.length - gotItCount - missedCount;
- const gap = cards.length <= 50 ? 3 : cards.length <= 120 ? 2 : cards.length <= 300 ? 1 : 0;
-
- return (
-
- {cards.map((card, index) => {
- const rating = reviewsByCardId[card.id]?.lastRating;
- const status = getFlashcardRatingLabel(rating);
- return (
-
- );
- })}
-
- );
-}
-
function getStudyCards(cardIds: string[], cardsById: ReadonlyMap): Flashcard[] {
const cards: Flashcard[] = [];
for (const cardId of cardIds) {
@@ -756,18 +697,21 @@ function getStudyCards(cardIds: string[], cardsById: ReadonlyMap 500 ? "is-very-dense" : textLength > 220 ? "is-dense" : undefined;
- const editor = useEditor(
- {
- content: content as unknown as JSONContent,
- editable: false,
- immediatelyRender: false,
- extensions: getTiptapDocumentBaseExtensions(),
- editorProps: {
- attributes: {
- class: cn(
- "workspace-document-prose workspace-flashcard-prose outline-none",
- densityClass,
- ),
- },
- },
- },
- [content],
- );
return (
{action}
-
+ sendComposerPrompt(
+ item.workspaceId,
+ `Give me a helpful hint for question ${sourceQuestionNumber} in “${itemPath}” without revealing the answer.`,
+ )
+ }
+ />
+ ) : null}
+
+
-
- {currentQuestion.options.map((option, optionIndex) => {
- const isSelected = answer?.selectedOptionId === option.id;
- const isCorrectOption = option.id === currentQuestion.correctOptionId;
- const graded = answer !== undefined;
- return (
-
- );
- })}
-
+
+ {currentQuestion.options.map((option, optionIndex) => {
+ const isSelected = option.id === selectedOptionId;
+ const isCorrectOption = option.id === currentQuestion.correctOptionId;
+ const previousOption = currentQuestion.options[optionIndex - 1];
+ return (
+
+
+ sendComposerPrompt(
+ item.workspaceId,
+ `Explain the answer to question ${sourceQuestionNumber} in “${itemPath}” in more depth.`,
+ )
+ }
+ />
+
+ {
+ const questionAnswer = getQuizAnswer(question, studyState);
+ const questionCorrect = questionAnswer?.selectedOptionId === question.correctOptionId;
+ return {
+ id: question.id,
+ label: `Question ${index + 1}: ${
+ !questionAnswer ? "Unanswered" : questionCorrect ? "Correct" : "Missed"
+ }`,
+ tone: !questionAnswer ? "unseen" : questionCorrect ? "correct" : "missed",
+ };
+ })}
+ />
+
+
+ {quizProgress.answeredCount} answered
+
+
+ goTo(currentIndex - 1)}
+ />
+
+ {currentIndex + 1} of {studyQuestions.length}
+
+ goTo(currentIndex + 1)}
+ />
+
+ {graded ? (
+
+ ) : (
+
+ )}
+
-
+
);
}
function QuizRichText({ content, compact }: { content: TiptapDocumentJson; compact?: boolean }) {
- const editor = useEditor(
- {
- content: content as unknown as JSONContent,
- editable: false,
- immediatelyRender: false,
- extensions: getTiptapDocumentBaseExtensions(),
- editorProps: {
- attributes: {
- class: cn("workspace-document-prose outline-none", compact && "text-sm"),
- },
- },
- },
- [content],
+ return (
+ Heading
", back: "A
" }]),
- ).toThrow("Flashcards do not support heading content yet.");
+ ).toThrow("Flashcard content cannot contain heading nodes.");
});
it("rejects empty sets and malformed stored rich text", () => {
diff --git a/src/features/workspaces/flashcards/flashcard-content.ts b/src/features/workspaces/flashcards/flashcard-content.ts
index aa404eff..baed067d 100644
--- a/src/features/workspaces/flashcards/flashcard-content.ts
+++ b/src/features/workspaces/flashcards/flashcard-content.ts
@@ -1,4 +1,7 @@
-import { createEntryRichTextParser } from "#/features/workspaces/content/entry-rich-text";
+import {
+ parseEntryRichTextHtml,
+ parseStoredEntryRichText,
+} from "#/features/workspaces/content/entry-rich-text";
import { serializeTiptapDocumentToHtml } from "#/features/workspaces/documents/document-ai-html";
import type { TiptapDocumentJson } from "#/features/workspaces/documents/tiptap-document";
import {
@@ -28,12 +31,6 @@ interface FlashcardHtmlCard {
back: string;
}
-const flashcardRichText = createEntryRichTextParser({
- invalidStored: "Flashcard content contains invalid rich text.",
- unsupportedMark: "Flashcard content contains an unsupported text mark.",
- unsupportedNode: (nodeType) => `Flashcards do not support ${nodeType} content yet.`,
-});
-
export function createFlashcardSetFromHtml(cards: Array<{ front: string; back: string }>) {
if (cards.length === 0) throw new Error("A flashcard set needs at least one card.");
return {
@@ -47,7 +44,7 @@ export function createFlashcardSetFromHtml(cards: Array<{ front: string; back: s
}
export function parseFlashcardSideHtml(html: string) {
- return flashcardRichText.parseEntryRichTextHtml(html);
+ return parseEntryRichTextHtml(html, "Flashcard");
}
export function parseFlashcardSetContent(content: string | null): FlashcardSetContent {
@@ -77,8 +74,8 @@ export function parseFlashcardSetContent(content: string | null): FlashcardSetCo
}
seenIds.add(cardId.data);
- const front = flashcardRichText.parseStoredEntryRichText(card.front);
- const back = flashcardRichText.parseStoredEntryRichText(card.back);
+ const front = parseStoredEntryRichText(card.front, "Flashcard");
+ const back = parseStoredEntryRichText(card.back, "Flashcard");
return { id: cardId.data, front, back };
});
diff --git a/src/features/workspaces/quizzes/quiz-content.test.ts b/src/features/workspaces/quizzes/quiz-content.test.ts
index f2aadd31..2c8fe8a0 100644
--- a/src/features/workspaces/quizzes/quiz-content.test.ts
+++ b/src/features/workspaces/quizzes/quiz-content.test.ts
@@ -49,7 +49,7 @@ describe("materializeQuizQuestion", () => {
it("rejects content outside the entry rich-text dialect", () => {
expect(() =>
materializeQuizQuestion({ ...atpQuestion, question: "Heading stem
" }),
- ).toThrow("Quizzes do not support heading content yet.");
+ ).toThrow("Quiz content cannot contain heading nodes.");
});
});
diff --git a/src/features/workspaces/quizzes/quiz-content.ts b/src/features/workspaces/quizzes/quiz-content.ts
index f78fa9f9..f9428168 100644
--- a/src/features/workspaces/quizzes/quiz-content.ts
+++ b/src/features/workspaces/quizzes/quiz-content.ts
@@ -1,4 +1,7 @@
-import { createEntryRichTextParser } from "#/features/workspaces/content/entry-rich-text";
+import {
+ parseEntryRichTextHtml,
+ parseStoredEntryRichText,
+} from "#/features/workspaces/content/entry-rich-text";
import { serializeTiptapDocumentToHtml } from "#/features/workspaces/documents/document-ai-html";
import type { TiptapDocumentJson } from "#/features/workspaces/documents/tiptap-document";
import {
@@ -52,14 +55,8 @@ export interface QuizQuestionInput {
explanation: string;
}
-const quizRichText = createEntryRichTextParser({
- invalidStored: "Quiz content contains invalid rich text.",
- unsupportedMark: "Quiz content contains an unsupported text mark.",
- unsupportedNode: (nodeType) => `Quizzes do not support ${nodeType} content yet.`,
-});
-
export function parseQuizRichTextHtml(html: string) {
- return quizRichText.parseEntryRichTextHtml(html);
+ return parseEntryRichTextHtml(html, "Quiz");
}
export function createQuizSetFromInputs(questions: QuizQuestionInput[]) {
@@ -87,13 +84,13 @@ export function materializeQuizQuestion(input: QuizQuestionInput): QuizQuestion
const correct = {
id: crypto.randomUUID(),
- text: quizRichText.parseEntryRichTextHtml(input.correctAnswer),
+ text: parseEntryRichTextHtml(input.correctAnswer, "Quiz"),
};
const options = [
correct,
...input.distractors.map((distractor) => ({
id: crypto.randomUUID(),
- text: quizRichText.parseEntryRichTextHtml(distractor),
+ text: parseEntryRichTextHtml(distractor, "Quiz"),
})),
];
assertDistinctOptions(options);
@@ -102,10 +99,10 @@ export function materializeQuizQuestion(input: QuizQuestionInput): QuizQuestion
return {
id: createWorkspaceEntryId("q"),
kind: "multiple_choice",
- question: quizRichText.parseEntryRichTextHtml(input.question),
+ question: parseEntryRichTextHtml(input.question, "Quiz"),
options,
correctOptionId: correct.id,
- explanation: quizRichText.parseEntryRichTextHtml(input.explanation),
+ explanation: parseEntryRichTextHtml(input.explanation, "Quiz"),
};
}
@@ -153,7 +150,7 @@ export function parseQuizSetContent(content: string | null): QuizSetContent {
throw new Error("Quiz content contains an invalid option ID.");
}
seenOptionIds.add(optionId.data);
- return { id: optionId.data, text: quizRichText.parseStoredEntryRichText(option.text) };
+ return { id: optionId.data, text: parseStoredEntryRichText(option.text, "Quiz") };
});
if (
typeof question.correctOptionId !== "string" ||
@@ -165,10 +162,10 @@ export function parseQuizSetContent(content: string | null): QuizSetContent {
return {
id: questionId.data,
kind: "multiple_choice" as const,
- question: quizRichText.parseStoredEntryRichText(question.question),
+ question: parseStoredEntryRichText(question.question, "Quiz"),
options,
correctOptionId: question.correctOptionId,
- explanation: quizRichText.parseStoredEntryRichText(question.explanation),
+ explanation: parseStoredEntryRichText(question.explanation, "Quiz"),
};
});
From 5f83e5c442e3e9cc6a7ada372fc909a43f400469 Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Sat, 15 Aug 2026 14:57:09 -0400
Subject: [PATCH 09/14] feat(workspaces): draw mermaid code blocks as diagrams
everywhere
Chat could already draw mermaid. Documents, flashcards, and quizzes
could not, which left diagrams out of exactly the surfaces that explain
things. A mermaid block is an ordinary code block, so cards and
questions get diagrams without opening their allowlist to widgets, which
stay documents-only.
AiChatMermaidDiagram becomes a shared MermaidDiagram taking isIncomplete
as a prop, since only chat can see a half-written fence, and caches
rendered SVGs so a card flipped back and forth does not re-render its
artwork. CodeBlockNodeView draws the diagram in place of the source and
selects the whole block on click, the way an image behaves. PDF export
drops mermaid blocks rather than printing authoring syntax.
Tool schemas gain one diagram instruction shared by all three item
types, plus a note that a diagram usually belongs in a quiz stem or
explanation, since one option taller than the rest hints at the answer.
---
.../code-block/mermaid-diagram.tsx} | 87 +++++++++++++++----
.../components/ai-chat/ai-chat-code-block.tsx | 11 ++-
.../code-block-shiki/CodeBlockNodeView.tsx | 40 ++++++++-
.../code-block-shiki/code-languages.ts | 10 +++
.../documents/code-block-shiki/highlighter.ts | 1 +
.../workspace-document-pdf-html.test.ts | 21 +++++
.../export/workspace-document-pdf-html.ts | 24 ++++-
.../workspace-tool-surface.test.ts.snap | 12 +--
.../operations/workspace-tool-schemas.ts | 14 ++-
src/styles.css | 15 ++++
10 files changed, 202 insertions(+), 33 deletions(-)
rename src/{features/workspaces/components/ai-chat/AiChatMermaidDiagram.tsx => components/code-block/mermaid-diagram.tsx} (80%)
diff --git a/src/features/workspaces/components/ai-chat/AiChatMermaidDiagram.tsx b/src/components/code-block/mermaid-diagram.tsx
similarity index 80%
rename from src/features/workspaces/components/ai-chat/AiChatMermaidDiagram.tsx
rename to src/components/code-block/mermaid-diagram.tsx
index 9519beb4..21a9723a 100644
--- a/src/features/workspaces/components/ai-chat/AiChatMermaidDiagram.tsx
+++ b/src/components/code-block/mermaid-diagram.tsx
@@ -1,6 +1,5 @@
import { Check, Copy, GitBranch, Maximize2, Minimize2, Minus, Plus } from "lucide-react";
import { useEffect, useId, useRef, useState } from "react";
-import { useIsCodeFenceIncomplete } from "streamdown";
import { useTheme } from "#/components/theme-provider";
import {
@@ -28,6 +27,24 @@ type MermaidRenderResult =
let mermaidRenderQueue = Promise.resolve();
+/**
+ * Rendered SVGs keyed by theme and source. Study surfaces mount the same
+ * diagram over and over — flipping a card back and forth, stepping through
+ * questions, or any edit that rebuilds the editor — and re-running mermaid
+ * each time would flash a placeholder over artwork the reader just saw.
+ * Cleared wholesale past a generous ceiling: an eviction policy would cost
+ * more than the few kilobytes it saves.
+ */
+const mermaidImageCache = new Map();
+const MAX_CACHED_DIAGRAMS = 64;
+
+function cacheMermaidImage(requestKey: string, image: MermaidImage) {
+ if (mermaidImageCache.size >= MAX_CACHED_DIAGRAMS) {
+ mermaidImageCache.clear();
+ }
+ mermaidImageCache.set(requestKey, image);
+}
+
function enqueueMermaidRender(input: { darkMode: boolean; id: string; source: string }) {
const render = mermaidRenderQueue.then(async () => {
const { default: mermaid } = await import("mermaid");
@@ -146,17 +163,30 @@ function useNearViewport() {
return { containerRef, isNearViewport };
}
-export function AiChatMermaidDiagram({ source }: { source: string }) {
- const isIncomplete = useIsCodeFenceIncomplete();
+/**
+ * Renders one mermaid source block as a diagram. Shared by chat, where the
+ * source streams in, and by document code blocks, where it arrives whole —
+ * hence `isIncomplete` as a prop rather than a hook: only chat can observe a
+ * half-written fence, and a document must not wait for a stream that has
+ * already ended.
+ */
+export function MermaidDiagram({
+ isIncomplete = false,
+ source,
+}: {
+ isIncomplete?: boolean;
+ source: string;
+}) {
const { resolvedTheme } = useTheme();
const reactId = useId();
const { containerRef, isNearViewport } = useNearViewport();
const requestKey = `${resolvedTheme}:${source}`;
const sourceIsTooLarge = source.length > MAX_MERMAID_SOURCE_LENGTH;
+ const cachedImage = mermaidImageCache.get(requestKey);
const [result, setResult] = useState(null);
useEffect(() => {
- if (!isNearViewport || isIncomplete || sourceIsTooLarge) {
+ if (!isNearViewport || isIncomplete || sourceIsTooLarge || cachedImage) {
return;
}
@@ -174,13 +204,15 @@ export function AiChatMermaidDiagram({ source }: { source: string }) {
return;
}
- setResult({ image: prepareMermaidImage(svg), requestKey, status: "ready" });
+ const image = prepareMermaidImage(svg);
+ cacheMermaidImage(requestKey, image);
+ setResult({ image, requestKey, status: "ready" });
} catch (error: unknown) {
if (cancelled) {
return;
}
- console.warn("[AiChatMermaidDiagram] Failed to render diagram", error);
+ console.warn("[MermaidDiagram] Failed to render diagram", error);
setResult({ requestKey, status: "error" });
}
})();
@@ -188,16 +220,39 @@ export function AiChatMermaidDiagram({ source }: { source: string }) {
return () => {
cancelled = true;
};
- }, [isIncomplete, isNearViewport, reactId, requestKey, resolvedTheme, source, sourceIsTooLarge]);
-
- const state: MermaidRenderResult | { status: "loading" } = sourceIsTooLarge
- ? { requestKey, status: "error" }
- : isIncomplete || result?.requestKey !== requestKey
- ? { status: "loading" }
- : result;
+ }, [
+ cachedImage,
+ isIncomplete,
+ isNearViewport,
+ reactId,
+ requestKey,
+ resolvedTheme,
+ source,
+ sourceIsTooLarge,
+ ]);
+
+ // A cache hit is read straight through to the render rather than copied
+ // into state, so a remount paints finished artwork on the first frame.
+ // This render's own result still outranks it: an ![]()
that failed to
+ // decode must not be answered with the cached image that just failed.
+ const state = ((): MermaidRenderResult | { status: "loading" } => {
+ if (sourceIsTooLarge) {
+ return { requestKey, status: "error" };
+ }
+ if (isIncomplete) {
+ return { status: "loading" };
+ }
+ if (result?.requestKey === requestKey) {
+ return result;
+ }
+ if (cachedImage) {
+ return { image: cachedImage, requestKey, status: "ready" };
+ }
+ return { status: "loading" };
+ })();
return (
-
+
{state.status === "loading" ? This diagram couldn’t be displayed, but the rest of the response is unaffected.
+ This diagram couldn’t be displayed. Its source is unchanged.
View diagram source
@@ -260,7 +315,7 @@ function MermaidDiagramCard({
const [zoom, setZoom] = useState(1);
const { copied, copy } = useCopyToClipboard({
onError: (error) => {
- console.warn("[AiChatMermaidDiagram] Failed to copy source", error);
+ console.warn("[MermaidDiagram] Failed to copy source", error);
},
});
diff --git a/src/features/workspaces/components/ai-chat/ai-chat-code-block.tsx b/src/features/workspaces/components/ai-chat/ai-chat-code-block.tsx
index fad3fcd1..4a8d30e8 100644
--- a/src/features/workspaces/components/ai-chat/ai-chat-code-block.tsx
+++ b/src/features/workspaces/components/ai-chat/ai-chat-code-block.tsx
@@ -2,6 +2,7 @@ import type { CSSProperties, HTMLAttributes, ReactNode } from "react";
import { isValidElement, useEffect, useState } from "react";
import type { ThemedToken } from "shiki/core";
import { ClientOnly } from "@tanstack/react-router";
+import { useIsCodeFenceIncomplete } from "streamdown";
import {
CodeBlockActions,
CodeBlockCopyButton,
@@ -13,10 +14,11 @@ import {
import {
getCodeLanguageLabel,
highlightCodeTokens,
+ isMermaidCodeLanguage,
normalizeCodeLanguage,
type SupportedCodeLanguage,
} from "#/features/workspaces/documents/code-block-shiki/highlighter";
-import { AiChatMermaidDiagram } from "#/features/workspaces/components/ai-chat/AiChatMermaidDiagram";
+import { MermaidDiagram } from "#/components/code-block/mermaid-diagram";
import { cn } from "#/lib/utils.ts";
// Shiki uses bitflags for font styles: 1=italic, 2=bold, 4=underline
@@ -358,6 +360,9 @@ export const MarkdownCodeBlock = ({
"data-block": dataBlock,
...props
}: MarkdownCodeBlockProps) => {
+ // Only chat can see a half-written fence, so the streaming state is read
+ // here and handed to the shared diagram rather than looked up inside it.
+ const isFenceIncomplete = useIsCodeFenceIncomplete();
const isBlock = dataBlock !== undefined;
if (!isBlock) {
@@ -375,10 +380,10 @@ export const MarkdownCodeBlock = ({
getLanguageFromClassName(className) ?? getLanguageFromClassName(node?.properties?.className);
const code = getTextContent(children).replace(/\n$/, "");
- if (rawLanguage?.toLowerCase() === "mermaid") {
+ if (isMermaidCodeLanguage(rawLanguage)) {
return (
-
);
}
diff --git a/src/features/workspaces/documents/code-block-shiki/CodeBlockNodeView.tsx b/src/features/workspaces/documents/code-block-shiki/CodeBlockNodeView.tsx
index 212ddfb7..cb7dac2c 100644
--- a/src/features/workspaces/documents/code-block-shiki/CodeBlockNodeView.tsx
+++ b/src/features/workspaces/documents/code-block-shiki/CodeBlockNodeView.tsx
@@ -13,18 +13,56 @@ import {
CodeBlockLanguageSelectorValue,
CodeBlockTitle,
} from "#/components/code-block/code-block-chrome";
+import { MermaidDiagram } from "#/components/code-block/mermaid-diagram";
import {
codeLanguageOptions,
getCodeLanguageLabel,
+ isMermaidCodeLanguage,
normalizeCodeLanguage,
type SupportedCodeLanguage,
} from "#/features/workspaces/documents/code-block-shiki/highlighter";
-export function CodeBlockNodeView({ node, updateAttributes }: ReactNodeViewProps) {
+export function CodeBlockNodeView({
+ editor,
+ getPos,
+ node,
+ selected,
+ updateAttributes,
+}: ReactNodeViewProps) {
const language = normalizeCodeLanguage(node.attrs.language as string | null);
const code = node.textContent;
const codeLanguage = language ?? "text";
+ /**
+ * A diagram is only ever the drawing, never the mermaid source that made
+ * it. Nobody hand-writes that syntax — the assistant authors and edits it —
+ * so a click selects the whole block to move or delete, the way an image
+ * behaves. The content stays mounted but hidden because ProseMirror still
+ * needs somewhere to keep the node's text.
+ */
+ if (isMermaidCodeLanguage(node.attrs.language as string | null)) {
+ return (
+ {
+ const position = getPos();
+ if (position !== undefined && editor.isEditable) {
+ // Focus first: a click on non-editable content leaves the
+ // editor blurred, and an unfocused selection ignores Backspace.
+ editor.chain().focus().setNodeSelection(position).run();
+ }
+ }}
+ >
+
+ );
+ }
+
return (
({ label, value }),
);
+/**
+ * Mermaid is deliberately not one of the languages above. It is never syntax
+ * highlighted, never offered in the language picker, and never read as source
+ * — every surface draws it instead — so registering a grammar for it would
+ * only ship a parser nothing looks at.
+ */
+export function isMermaidCodeLanguage(language: string | null | undefined) {
+ return language?.trim().toLowerCase() === "mermaid";
+}
+
export const supportedCodeFileExtensions = [
...new Set(codeLanguageDefinitionList.flatMap((definition) => definition.extensions ?? [])),
].sort((left, right) => left.localeCompare(right));
diff --git a/src/features/workspaces/documents/code-block-shiki/highlighter.ts b/src/features/workspaces/documents/code-block-shiki/highlighter.ts
index 26d4c3e7..4fe9a7a9 100644
--- a/src/features/workspaces/documents/code-block-shiki/highlighter.ts
+++ b/src/features/workspaces/documents/code-block-shiki/highlighter.ts
@@ -13,6 +13,7 @@ import { createJavaScriptRegexEngine } from "shiki/engine/javascript";
export {
codeLanguageOptions,
getCodeLanguageLabel,
+ isMermaidCodeLanguage,
normalizeCodeLanguage,
type CodeLanguageOption,
type SupportedCodeLanguage,
diff --git a/src/features/workspaces/export/workspace-document-pdf-html.test.ts b/src/features/workspaces/export/workspace-document-pdf-html.test.ts
index 34e8b2ee..c26eb347 100644
--- a/src/features/workspaces/export/workspace-document-pdf-html.test.ts
+++ b/src/features/workspaces/export/workspace-document-pdf-html.test.ts
@@ -70,4 +70,25 @@ describe("renderWorkspaceDocumentPdfHtml", () => {
expect(html).toContain("math-fallback");
expect(html).toContain("$\\definitelynotacommand{$");
});
+
+ // A PDF cannot draw the diagram, and its source is authoring material the
+ // reader never asked for, so the block leaves nothing behind.
+ it("drops a mermaid diagram rather than printing its source", async () => {
+ const html = await renderWorkspaceDocumentPdfHtml({
+ type: "doc",
+ content: [
+ {
+ type: "codeBlock",
+ attrs: { language: "mermaid" },
+ content: [{ type: "text", text: "flowchart TD; A[Start] --> B[End]" }],
+ },
+ { type: "paragraph", content: [{ type: "text", text: "Prose survives." }] },
+ ],
+ });
+
+ expect(html).toContain("Prose survives.");
+ expect(html).not.toContain("flowchart");
+ expect(html).not.toContain("Mermaid");
+ expect(html).not.toContain("language-mermaid");
+ });
});
diff --git a/src/features/workspaces/export/workspace-document-pdf-html.ts b/src/features/workspaces/export/workspace-document-pdf-html.ts
index 262387d9..d5360c73 100644
--- a/src/features/workspaces/export/workspace-document-pdf-html.ts
+++ b/src/features/workspaces/export/workspace-document-pdf-html.ts
@@ -5,6 +5,7 @@ import { parseHTML } from "linkedom";
import {
getCodeLanguageLabel,
highlightCodeTokens,
+ isMermaidCodeLanguage,
} from "#/features/workspaces/documents/code-block-shiki/highlighter";
import type { TiptapDocumentJson } from "#/features/workspaces/documents/tiptap-document";
import { getTiptapDocumentSchema } from "#/features/workspaces/documents/tiptap-schema";
@@ -102,10 +103,28 @@ export async function renderWorkspaceDocumentPdfHtml(document: TiptapDocumentJso
return `${article.outerHTML}`;
}
+/**
+ * What a printed page cannot carry. A citation has nothing to link to; a
+ * widget is markup that has to run; a mermaid block is an instruction for
+ * drawing rather than the drawing. Falling back to source for the last two
+ * would put authoring material in front of a reader who asked for a document,
+ * so all three leave nothing behind.
+ */
function removeUnexportedNodes(article: Element) {
for (const node of article.querySelectorAll('citation, [data-type="widget"]')) {
node.remove();
}
+ for (const code of article.querySelectorAll("pre > code")) {
+ if (isMermaidCodeLanguage(readCodeBlockLanguage(code))) {
+ code.parentElement?.remove();
+ }
+ }
+}
+
+/** The language a code block declares, exactly as it was written. */
+function readCodeBlockLanguage(element: Element) {
+ const languageClass = Array.from(element.classList).find((name) => name.startsWith("language-"));
+ return languageClass?.slice("language-".length) || null;
}
function renderMath(article: Element) {
@@ -133,11 +152,8 @@ async function renderCodeBlocks(htmlDocument: Document, article: Element) {
const codeBlocks = Array.from(article.querySelectorAll("pre > code"));
const rendered = await Promise.all(
codeBlocks.map(async (element) => {
- const languageClass = Array.from(element.classList).find((name) =>
- name.startsWith("language-"),
- );
const code = element.textContent ?? "";
- const language = languageClass?.slice("language-".length) || null;
+ const language = readCodeBlockLanguage(element);
return {
code,
element,
diff --git a/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap b/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap
index 916c1cb2..8039e895 100644
--- a/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap
+++ b/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap
@@ -105,7 +105,7 @@ exports[`workspace tool surface > workspace_create_items input schema is stable
"description": "Document to create.",
"properties": {
"initialContent": {
- "description": "Optional initial HTML content. Use semantic HTML with paragraphs, h1-h4, blockquotes, lists, code blocks, horizontal rules, tables, links, and standard text marks. This is HTML, so math is markup rather than delimiters: use or , and keep dollar signs out of the data-latex value. Put every subscript and superscript (exponents like 10^8, indices like x_1) inside math rather than / tags. Chemistry renders with \\ce{...} (e.g. \\ce{CH4 + 2 O2 -> CO2 + 2 H2O}) and quantities with units render with \\pu{...} (e.g. \\pu{9.81 m/s^2}), both inside data-latex. Write literal money as plain text ($30, never \\$30) — a backslash before a dollar sign shows on screen in HTML. For checkboxes, use Item
. Documents cannot hold images: never use ![]()
or , and describe the visual in words instead. Cite workspace sources in documents exactly as in a chat reply, with Item
. Documents cannot hold images: never use ![]()
or — draw a diagram or describe the visual in words instead. Draw a diagram as a mermaid code block: flowchart TD; A[Start] --> B[End]
. It renders as a diagram wherever the item is read or studied, and is left out of a PDF export entirely, so never let a diagram carry a point the surrounding text does not also make. Keep it to about ten nodes with short labels, and include concise accTitle and accDescr lines — they become the diagram's alt text. No frontmatter, init directives, custom styles, HTML, links, or images inside the diagram. Cite workspace sources in documents exactly as in a chat reply, with flowchart TD; A[Start] --> B[End]
. It renders as a diagram wherever the item is read or studied, and is left out of a PDF export entirely, so never let a diagram carry a point the surrounding text does not also make. Keep it to about ten nodes with short labels, and include concise accTitle and accDescr lines — they become the diagram's alt text. No frontmatter, init directives, custom styles, HTML, links, or images inside the diagram. Use item-level relations for sources.",
"items": {
"additionalProperties": false,
"properties": {
@@ -250,7 +250,7 @@ exports[`workspace tool surface > workspace_create_items input schema is stable
"type": "string",
},
"questions": {
- "description": "Ordered multiple-choice questions. Question stems, options, and explanations are HTML. Keep them concise. Use paragraphs, lists, links, code blocks, and standard text marks only. This is HTML, so math is markup rather than delimiters: use or , and keep dollar signs out of the data-latex value. Put every subscript and superscript (exponents like 10^8, indices like x_1) inside math rather than / tags. Chemistry renders with \\ce{...} (e.g. \\ce{CH4 + 2 O2 -> CO2 + 2 H2O}) and quantities with units render with \\pu{...} (e.g. \\pu{9.81 m/s^2}), both inside data-latex. Write literal money as plain text ($30, never \\$30) — a backslash before a dollar sign shows on screen in HTML. Do not use headings, tables, images, widgets, task lists, or citations inside a question. Use item-level relations for sources. Write correctAnswer as its own field and never hint at it in the stem or option order: the server shuffles the options and records which one is correct. Every distractor must be strictly wrong yet plausible, reflect a specific misconception, and match the correct answer's length and tone. Prefer 3 distractors; use 1 for true/false. Questions should test understanding from the source material, not trivia recall.",
+ "description": "Ordered multiple-choice questions. Question stems, options, and explanations are HTML. Keep them concise. Use paragraphs, lists, links, code blocks, and standard text marks only. This is HTML, so math is markup rather than delimiters: use or , and keep dollar signs out of the data-latex value. Put every subscript and superscript (exponents like 10^8, indices like x_1) inside math rather than / tags. Chemistry renders with \\ce{...} (e.g. \\ce{CH4 + 2 O2 -> CO2 + 2 H2O}) and quantities with units render with \\pu{...} (e.g. \\pu{9.81 m/s^2}), both inside data-latex. Write literal money as plain text ($30, never \\$30) — a backslash before a dollar sign shows on screen in HTML. Do not use headings, tables, images, widgets, task lists, or citations inside a question. Draw a diagram as a mermaid code block: flowchart TD; A[Start] --> B[End]
. It renders as a diagram wherever the item is read or studied, and is left out of a PDF export entirely, so never let a diagram carry a point the surrounding text does not also make. Keep it to about ten nodes with short labels, and include concise accTitle and accDescr lines — they become the diagram's alt text. No frontmatter, init directives, custom styles, HTML, links, or images inside the diagram. A diagram usually belongs in the stem or the explanation; if one option needs it, give them all one, since an option taller than the rest hints at the answer. Use item-level relations for sources. Write correctAnswer as its own field and never hint at it in the stem or option order: the server shuffles the options and records which one is correct. Every distractor must be strictly wrong yet plausible, reflect a specific misconception, and match the correct answer's length and tone. Prefer 3 distractors; use 1 for true/false. Questions should test understanding from the source material, not trivia recall.",
"items": {
"additionalProperties": false,
"properties": {
@@ -387,7 +387,7 @@ exports[`workspace tool surface > workspace_edit_item input schema is stable 1`]
"description": "Document edits.",
"properties": {
"edits": {
- "description": "Ordered document edits using exact refs from a read. Available operations: insert_before, insert_after, update, replace, replace_text, move, and delete. update accepts exactly one top-level block; replace may replace one block with several. move requires exactly one of beforeRef or afterRef. Use semantic HTML with paragraphs, h1-h4, blockquotes, lists, code blocks, horizontal rules, tables, links, and standard text marks. This is HTML, so math is markup rather than delimiters: use or , and keep dollar signs out of the data-latex value. Put every subscript and superscript (exponents like 10^8, indices like x_1) inside math rather than / tags. Chemistry renders with \\ce{...} (e.g. \\ce{CH4 + 2 O2 -> CO2 + 2 H2O}) and quantities with units render with \\pu{...} (e.g. \\pu{9.81 m/s^2}), both inside data-latex. Write literal money as plain text ($30, never \\$30) — a backslash before a dollar sign shows on screen in HTML. For checkboxes, use Item
. Documents cannot hold images: never use ![]()
or , and describe the visual in words instead. Cite workspace sources in documents exactly as in a chat reply, with Item
. Documents cannot hold images: never use ![]()
or — draw a diagram or describe the visual in words instead. Draw a diagram as a mermaid code block: flowchart TD; A[Start] --> B[End]
. It renders as a diagram wherever the item is read or studied, and is left out of a PDF export entirely, so never let a diagram carry a point the surrounding text does not also make. Keep it to about ten nodes with short labels, and include concise accTitle and accDescr lines — they become the diagram's alt text. No frontmatter, init directives, custom styles, HTML, links, or images inside the diagram. Cite workspace sources in documents exactly as in a chat reply, with flowchart TD; A[Start] --> B[End]
. It renders as a diagram wherever the item is read or studied, and is left out of a PDF export entirely, so never let a diagram carry a point the surrounding text does not also make. Keep it to about ten nodes with short labels, and include concise accTitle and accDescr lines — they become the diagram's alt text. No frontmatter, init directives, custom styles, HTML, links, or images inside the diagram. Use item-level relations for sources.",
"items": {
"anyOf": [
{
@@ -733,7 +733,7 @@ exports[`workspace tool surface > workspace_edit_item input schema is stable 1`]
"description": "Quiz edits.",
"properties": {
"edits": {
- "description": "Ordered quiz edits using exact refs from a read. Available operations: insert_before, insert_after, update, replace, replace_text, move, and delete. insert and replace take a full authored question and reshuffle its options; update changes only the stem or explanation in place; replace_text requires question, options, or explanation as field and never reshuffles; move requires exactly one of beforeRef or afterRef. Question stems, options, and explanations are HTML. Keep them concise. Use paragraphs, lists, links, code blocks, and standard text marks only. This is HTML, so math is markup rather than delimiters: use or , and keep dollar signs out of the data-latex value. Put every subscript and superscript (exponents like 10^8, indices like x_1) inside math rather than / tags. Chemistry renders with \\ce{...} (e.g. \\ce{CH4 + 2 O2 -> CO2 + 2 H2O}) and quantities with units render with \\pu{...} (e.g. \\pu{9.81 m/s^2}), both inside data-latex. Write literal money as plain text ($30, never \\$30) — a backslash before a dollar sign shows on screen in HTML. Do not use headings, tables, images, widgets, task lists, or citations inside a question. Use item-level relations for sources. Write correctAnswer as its own field and never hint at it in the stem or option order: the server shuffles the options and records which one is correct. Every distractor must be strictly wrong yet plausible, reflect a specific misconception, and match the correct answer's length and tone. Prefer 3 distractors; use 1 for true/false. Questions should test understanding from the source material, not trivia recall.",
+ "description": "Ordered quiz edits using exact refs from a read. Available operations: insert_before, insert_after, update, replace, replace_text, move, and delete. insert and replace take a full authored question and reshuffle its options; update changes only the stem or explanation in place; replace_text requires question, options, or explanation as field and never reshuffles; move requires exactly one of beforeRef or afterRef. Question stems, options, and explanations are HTML. Keep them concise. Use paragraphs, lists, links, code blocks, and standard text marks only. This is HTML, so math is markup rather than delimiters: use or , and keep dollar signs out of the data-latex value. Put every subscript and superscript (exponents like 10^8, indices like x_1) inside math rather than / tags. Chemistry renders with \\ce{...} (e.g. \\ce{CH4 + 2 O2 -> CO2 + 2 H2O}) and quantities with units render with \\pu{...} (e.g. \\pu{9.81 m/s^2}), both inside data-latex. Write literal money as plain text ($30, never \\$30) — a backslash before a dollar sign shows on screen in HTML. Do not use headings, tables, images, widgets, task lists, or citations inside a question. Draw a diagram as a mermaid code block: flowchart TD; A[Start] --> B[End]
. It renders as a diagram wherever the item is read or studied, and is left out of a PDF export entirely, so never let a diagram carry a point the surrounding text does not also make. Keep it to about ten nodes with short labels, and include concise accTitle and accDescr lines — they become the diagram's alt text. No frontmatter, init directives, custom styles, HTML, links, or images inside the diagram. A diagram usually belongs in the stem or the explanation; if one option needs it, give them all one, since an option taller than the rest hints at the answer. Use item-level relations for sources. Write correctAnswer as its own field and never hint at it in the stem or option order: the server shuffles the options and records which one is correct. Every distractor must be strictly wrong yet plausible, reflect a specific misconception, and match the correct answer's length and tone. Prefer 3 distractors; use 1 for true/false. Questions should test understanding from the source material, not trivia recall.",
"items": {
"anyOf": [
{
diff --git a/src/features/workspaces/operations/workspace-tool-schemas.ts b/src/features/workspaces/operations/workspace-tool-schemas.ts
index 249a88d6..d36db2e8 100644
--- a/src/features/workspaces/operations/workspace-tool-schemas.ts
+++ b/src/features/workspaces/operations/workspace-tool-schemas.ts
@@ -36,17 +36,25 @@ export { workspaceReadItemsInputSchema, workspaceReadItemsOutputSchema };
const workspaceHtmlMathInstruction =
'This is HTML, so math is markup rather than delimiters: use or , and keep dollar signs out of the data-latex value. Put every subscript and superscript (exponents like 10^8, indices like x_1) inside math rather than / tags. Chemistry renders with \\ce{...} (e.g. \\ce{CH4 + 2 O2 -> CO2 + 2 H2O}) and quantities with units render with \\pu{...} (e.g. \\pu{9.81 m/s^2}), both inside data-latex. Write literal money as plain text ($30, never \\$30) — a backslash before a dollar sign shows on screen in HTML.';
+/**
+ * The one diagram route every HTML surface shares. A mermaid block is an
+ * ordinary code block, so cards and questions get diagrams without opening
+ * their allowlist to widgets — which stay documents-only.
+ */
+const workspaceHtmlDiagramInstruction =
+ 'Draw a diagram as a mermaid code block: flowchart TD; A[Start] --> B[End]
. It renders as a diagram wherever the item is read or studied, and is left out of a PDF export entirely, so never let a diagram carry a point the surrounding text does not also make. Keep it to about ten nodes with short labels, and include concise accTitle and accDescr lines — they become the diagram\'s alt text. No frontmatter, init directives, custom styles, HTML, links, or images inside the diagram.';
+
/**
* Keep discovery and serialization beside the document tool. The activated
* skill owns the authoring contract so the two prompts cannot drift apart.
*/
const workspaceWidgetHtmlInstruction = `A widget is one interactive block inside a document. Use one when the user explicitly asks for a widget, asks for interaction or live computation, or wants a document visual that ordinary blocks cannot express. Keep ordinary content in ordinary blocks. Before authoring or editing widget source, activate the "widget-authoring" skill and follow its HTML, sandbox, layout, and editing contract. Serialize the result as …HTML-escaped fragment….`;
-export const workspaceDocumentHtmlInstruction = `Use semantic HTML with paragraphs, h1-h4, blockquotes, lists, code blocks, horizontal rules, tables, links, and standard text marks. ${workspaceHtmlMathInstruction} For checkboxes, use Item
. Documents cannot hold images: never use ![]()
or , and describe the visual in words instead. Cite workspace sources in documents exactly as in a chat reply, with Item
. Documents cannot hold images: never use ![]()
or — draw a diagram or describe the visual in words instead. ${workspaceHtmlDiagramInstruction} Cite workspace sources in documents exactly as in a chat reply, with
{
diff --git a/src/features/workspaces/components/quizzes/QuizViewer.tsx b/src/features/workspaces/components/quizzes/QuizViewer.tsx
index 74054ef8..3ac924e8 100644
--- a/src/features/workspaces/components/quizzes/QuizViewer.tsx
+++ b/src/features/workspaces/components/quizzes/QuizViewer.tsx
@@ -10,6 +10,7 @@ import { StudyRichText } from "#/features/workspaces/components/study/StudyRichT
import {
StudyAiActionButton,
StudyNavButton,
+ useStudySessionFocus,
} from "#/features/workspaces/components/study/StudySessionControls";
import { StudyToolbar } from "#/features/workspaces/components/study/StudyToolbar";
import { useWorkspaceItemToolbar } from "#/features/workspaces/components/WorkspaceItemToolbarSlot";
@@ -119,6 +120,7 @@ function QuizStudySession({
? questions.findIndex((question) => question.id === currentQuestion.id) + 1
: 0;
const answer = currentQuestion ? getQuizAnswer(currentQuestion, studyState) : undefined;
+ const sectionRef = useStudySessionFocus(currentQuestion?.id);
const quizProgress = useMemo(
() => summarizeQuizStudyProgress(questions, studyState),
[questions, studyState],
@@ -299,6 +301,7 @@ function QuizStudySession({
return (
— out of reach of the section's
+ * keydown handler. Attach the returned ref to the section; when an entry change
+ * strands focus on , the section takes it back.
+ */
+export function useStudySessionFocus(entryKey: string | undefined) {
+ const sectionRef = useRef(null);
+ const previousKey = useRef(entryKey);
+ useEffect(() => {
+ if (previousKey.current === entryKey) return;
+ previousKey.current = entryKey;
+ if (document.activeElement === document.body) sectionRef.current?.focus();
+ }, [entryKey]);
+ return sectionRef;
+}
+
/**
* Asks the AI for help with the item on screen — a hint before answering, a
* fuller explanation after. Amber everywhere so "ask AI" reads the same in
From 2aa4b94454afd5f6225caac61c3dd75e3834593a Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Sat, 15 Aug 2026 15:28:43 -0400
Subject: [PATCH 12/14] fix(workspaces): show a static language label in
read-only code blocks
The node view assumed its host was the editable document editor; study
viewers now render it read-only, where the language dropdown is editing
chrome with nothing to edit.
---
.../code-block-shiki/CodeBlockNodeView.tsx | 56 ++++++++++---------
1 file changed, 31 insertions(+), 25 deletions(-)
diff --git a/src/features/workspaces/documents/code-block-shiki/CodeBlockNodeView.tsx b/src/features/workspaces/documents/code-block-shiki/CodeBlockNodeView.tsx
index cb7dac2c..07b7215d 100644
--- a/src/features/workspaces/documents/code-block-shiki/CodeBlockNodeView.tsx
+++ b/src/features/workspaces/documents/code-block-shiki/CodeBlockNodeView.tsx
@@ -71,32 +71,38 @@ export function CodeBlockNodeView({
>
- {
- updateAttributes({
- language: value === "plain" ? null : (value as SupportedCodeLanguage),
- });
- }}
- >
-
-
- {(value: string | null) =>
- value === "plain" ? "Plain text" : getCodeLanguageLabel(value)
- }
-
-
-
-
- Plain text
-
- {codeLanguageOptions.map((option) => (
-
- {option.label}
+ {/* Study viewers render this node view read-only, where the
+ language is a fact to show, not a setting to change. */}
+ {editor.isEditable ? (
+ {
+ updateAttributes({
+ language: value === "plain" ? null : (value as SupportedCodeLanguage),
+ });
+ }}
+ >
+
+
+ {(value: string | null) =>
+ value === "plain" ? "Plain text" : getCodeLanguageLabel(value)
+ }
+
+
+
+
+ Plain text
- ))}
-
-
+ {codeLanguageOptions.map((option) => (
+
+ {option.label}
+
+ ))}
+
+
+ ) : (
+ getCodeLanguageLabel(language)
+ )}
();
for (const ref of new Set(refs)) {
const address = parseWorkspaceAddress(ref);
if (!address) continue;
- const resolved = await getWorkspaceItemByRefKey({
- refKey: address.refKey,
- workspaceId: input.context.workspaceId,
- });
+ const resolved = refKeyIndex.get(address.refKey);
const location = resolved ? resolveWorkspaceAddressLocation(resolved.item, address) : undefined;
if (location) locations.set(ref, location);
}
diff --git a/src/features/workspaces/operations/read-items.ts b/src/features/workspaces/operations/read-items.ts
index 8f4ba239..9e1a9214 100644
--- a/src/features/workspaces/operations/read-items.ts
+++ b/src/features/workspaces/operations/read-items.ts
@@ -9,7 +9,7 @@ import { recordWorkspaceFileReadOutcomes } from "#/features/workspaces/content/w
import { getDocumentSessionFromEnv } from "#/features/workspaces/document-session-access";
import { readFlashcardViewer } from "#/features/workspaces/flashcards/flashcard-study-persistence";
import { readQuizViewer } from "#/features/workspaces/quizzes/quiz-study-persistence";
-import { getWorkspaceItemByRefKey } from "#/features/workspaces/persistence/workspace-items";
+import { getWorkspaceItemRefKeyIndex } from "#/features/workspaces/persistence/workspace-items";
import type { WorkspaceAccessContext } from "#/features/workspaces/operations/workspace-access-context";
import { authorizeWorkspaceOperation } from "#/features/workspaces/operations/workspace-operation-context";
@@ -25,6 +25,8 @@ export async function readWorkspaceItemsOperation(
access: "read",
context: accessContext,
});
+ // Lazy so path-only batches skip it; shared so N ref requests cost one page read.
+ let refKeyIndex: ReturnType | undefined;
const results = await readWorkspaceContent({
bucket: env.WORKSPACE_FILES,
getDocumentSession: (itemId) =>
@@ -44,8 +46,10 @@ export async function readWorkspaceItemsOperation(
userId: accessContext.actor.userId,
workspaceId: accessContext.workspaceId,
}),
- resolveRefKey: (refKey) =>
- getWorkspaceItemByRefKey({ refKey, workspaceId: accessContext.workspaceId }),
+ resolveRefKey: async (refKey) => {
+ refKeyIndex ??= getWorkspaceItemRefKeyIndex({ workspaceId: accessContext.workspaceId });
+ return (await refKeyIndex).get(refKey);
+ },
requests: input.requests,
workspaceId: accessContext.workspaceId,
});
diff --git a/src/features/workspaces/persistence/workspace-items.ts b/src/features/workspaces/persistence/workspace-items.ts
index 49ee9328..32fd245c 100644
--- a/src/features/workspaces/persistence/workspace-items.ts
+++ b/src/features/workspaces/persistence/workspace-items.ts
@@ -124,13 +124,20 @@ export async function getWorkspaceItemPaths(input: WorkspaceScoped) {
+/**
+ * Resolves item address refKeys to live items and their paths. Costs one
+ * workspace page read however many refKeys the caller then looks up, so
+ * callers with several refs to resolve share a single index.
+ */
+export async function getWorkspaceItemRefKeyIndex(input: WorkspaceScoped
");
expect(contents[2]).toContain(">Tail");
});
- it("rejects a nonzero continuation offset for an empty document", async () => {
- const read = createReader({
- bucket: {} as R2Bucket,
- getDocumentSession: () => createDocumentSession({ html: "", revision: "revision-1" }),
- });
- const cursor = encodeWorkspaceContentCursor({
- kind: "document",
- offset: 1,
- path: "/Notes",
- revision: "revision-1",
- version: 3,
- });
-
- await expect(read([{ cursor, mode: "continue", path: "/Notes" }])).resolves.toEqual([
- { code: "invalid_cursor", path: "/Notes", status: "failed" },
- ]);
- });
-
- it("rejects a continuation cursor issued for another path", async () => {
- const read = createReader({
- bucket: {} as R2Bucket,
- getDocumentSession: () => createDocumentSession({ html: "", revision: "revision-1" }),
- });
- const cursor = encodeWorkspaceContentCursor({
- kind: "document",
- offset: 0,
- path: "/Other",
- revision: "revision-1",
- version: 3,
- });
-
- await expect(read([{ cursor, mode: "continue", path: "/Notes" }])).resolves.toEqual([
- { code: "invalid_cursor", path: "/Notes", status: "failed" },
- ]);
- });
-
it("bounds total content returned by a batch", async () => {
const read = createReader({
bucket: {} as R2Bucket,
- getDocumentSession: () =>
- createDocumentSession({
- html: `${"😀".repeat(300_000)}
`,
- revision: "revision-1",
- }),
+ getDocumentSession: () => createDocumentSession({ html: `${"😀".repeat(300_000)}
` }),
});
- const requests = Array.from({ length: 20 }, (_, index) => ({
+ const requests = Array.from({ length: 3 }, (_, index) => ({
mode: "start" as const,
path: `/Notes ${index + 1}`,
}));
const results = await read(requests);
expect(results.filter((result) => result.status === "ready")).toHaveLength(1);
- expect(results.slice(1)).toEqual(
+ expect(results.slice(1)).toMatchObject(
requests.slice(1).map((request) => ({
code: "read_budget_exceeded",
path: request.path,
@@ -346,11 +289,12 @@ describe("WorkspaceContentReader", () => {
// One session across both reads: a fresh one would mint new refs.
const session = createDocumentSession({
html: `Before
${source.replaceAll("<", "<")}`,
- revision: "revision-1",
});
const read = createReader({
bucket: {} as R2Bucket,
getDocumentSession: () => session,
+ resolveRefKey: async (refKey) =>
+ refKey === documentItem.refKey ? { item: documentItem, path: "/Notes" } : undefined,
});
const [chunk] = await read([{ mode: "start", path: "/Notes" }]);
@@ -362,21 +306,9 @@ describe("WorkspaceContentReader", () => {
const widgetTag = /]*data-type="widget"[^>]*>/.exec(chunk.content)?.[0] ?? "";
const contentRef = /data-ref="([^"]+)"/.exec(widgetTag)?.[1];
expect(contentRef).toBeTruthy();
+ const blockId = contentRef!.split(".")[0]!;
- const readBlock = createReader({
- bucket: {} as R2Bucket,
- getDocumentSession: () => session,
- resolveReference: (_itemId, ref) =>
- ref === "wr_AAAAAAAA"
- ? {
- blockId: parseDocumentAiRef(contentRef!)!,
- itemId: documentItem.id,
- kind: "document-block",
- version: 1,
- }
- : undefined,
- });
- const [block] = await readBlock([{ ref: "wr_AAAAAAAA", mode: "ref", path: "/Notes" }]);
+ const [block] = await read([{ mode: "ref", ref: `refdoc01/${blockId}` }]);
expect(block).toMatchObject({ contentRef, status: "ready", type: "block" });
if (!block || block.status !== "ready" || block.type !== "block") {
throw new Error("Expected a block read.");
@@ -385,34 +317,34 @@ describe("WorkspaceContentReader", () => {
expect(block.content).not.toContain("data-ref");
});
- it("rejects unknown exact refs", async () => {
- const fileItem = {
- ...documentItem,
- id: "file-1",
- name: "Book.pdf",
- type: "file",
- } satisfies WorkspaceItem;
+ it("rejects unknown addresses", async () => {
const read = createReader({
bucket: {} as R2Bucket,
- getDocumentSession: () => createDocumentSession({ html: "", revision: "revision-1" }),
- item: fileItem,
+ getDocumentSession: () => createDocumentSession({ html: "" }),
});
- await expect(
- read([
- {
- ref: "wr_AAAAAAAA",
- mode: "ref",
- path: "/Book.pdf",
- },
- ]),
- ).resolves.toEqual([{ code: "ref_not_found", path: "/Book.pdf", status: "failed" }]);
+ await expect(read([{ mode: "ref", ref: "zzZZzzZZ/p5" }])).resolves.toEqual([
+ { code: "ref_not_found", ref: "zzZZzzZZ/p5", status: "failed" },
+ ]);
+ });
+
+ it("rejects a unit that cannot belong to the item's type", async () => {
+ const read = createReader({
+ bucket: {} as R2Bucket,
+ getDocumentSession: () => createDocumentSession({ html: "a
" }),
+ resolveRefKey: async (refKey) =>
+ refKey === documentItem.refKey ? { item: documentItem, path: "/Notes" } : undefined,
+ });
+
+ await expect(read([{ mode: "ref", ref: "refdoc01/p5" }])).resolves.toEqual([
+ { code: "ref_not_found", ref: "refdoc01/p5", status: "failed" },
+ ]);
});
it("keeps one ordered result for every requested path", async () => {
const read = createReader({
bucket: {} as R2Bucket,
- getDocumentSession: () => createDocumentSession({ html: "", revision: "revision-1" }),
+ getDocumentSession: () => createDocumentSession({ html: "" }),
resolvePaths: vi.fn(
async () =>
[
@@ -437,18 +369,13 @@ describe("WorkspaceContentReader", () => {
});
});
-function createDocumentSession(input: { html: string; revision: string }) {
+function createDocumentSession(input: { html: string }) {
const document = ensureTiptapDocumentBlockIds(parseDocumentAiHtml(input.html)).document;
const documentNode = getTiptapDocumentSchema().nodeFromJSON(document);
return {
- readHtmlChunk: vi.fn(async ({ expectedRevision, offset }) => {
- if (expectedRevision && expectedRevision !== input.revision) {
- return { status: "content_changed" as const };
- }
- const chunk = await readDocumentHtmlChunk(documentNode, offset);
- return chunk
- ? { ...chunk, revision: input.revision, status: "ready" as const }
- : { status: "invalid_offset" as const };
+ readHtmlChunk: vi.fn(async ({ offset, maxBlocks }: { offset: number; maxBlocks?: number }) => {
+ const chunk = await readDocumentHtmlChunk(documentNode, offset, maxBlocks);
+ return chunk ? { ...chunk, status: "ready" as const } : { status: "invalid_offset" as const };
}),
readBlock: vi.fn(async ({ blockId }: { blockId: string }) => {
let found: ReturnType | null = null;
@@ -480,7 +407,8 @@ function createReader(input: {
cards: ReturnType["cards"];
studyState: FlashcardStudyState;
}>;
- resolveReference?: Parameters[0]["resolveReference"];
+ readQuizItem?: Parameters[0]["readQuizItem"];
+ resolveRefKey?: Parameters[0]["resolveRefKey"];
resolvePaths?: typeof persistence.resolveWorkspacePaths;
}) {
const item = input.item ?? documentItem;
@@ -499,7 +427,10 @@ function createReader(input: {
readFlashcardItem:
input.readFlashcardItem ??
(async () => ({ cards: [], studyState: { kind: "flashcard", cards: {} } })),
- resolveReference: input.resolveReference,
+ readQuizItem:
+ input.readQuizItem ??
+ (async () => ({ questions: [], studyState: { kind: "quiz", answers: {} } })),
+ resolveRefKey: input.resolveRefKey ?? (async () => undefined),
requests,
workspaceId: "workspace-1",
});
diff --git a/src/features/workspaces/content/workspace-content-reader.ts b/src/features/workspaces/content/workspace-content-reader.ts
index 4349e295..6119389a 100644
--- a/src/features/workspaces/content/workspace-content-reader.ts
+++ b/src/features/workspaces/content/workspace-content-reader.ts
@@ -1,8 +1,4 @@
-import {
- type WorkspaceItem,
- getWorkspaceItemContentKind,
- isWorkspaceItemContainer,
-} from "#/features/workspaces/contracts";
+import { type WorkspaceItem, isWorkspaceItemContainer } from "#/features/workspaces/contracts";
import type {
WorkspaceContentReadRequest,
WorkspaceContentReadResult,
@@ -29,24 +25,35 @@ import {
parseWorkspacePageRange,
WorkspacePageSelectionError,
} from "#/features/workspaces/read-page-selection";
-import {
- decodeWorkspaceContentCursor,
- encodeWorkspaceContentCursor,
-} from "#/features/workspaces/content/workspace-content-cursor";
import {
createFlashcardRevision,
type Flashcard,
serializeFlashcardSetToHtml,
} from "#/features/workspaces/flashcards/flashcard-content";
-import type { WorkspaceLocation } from "#/features/workspaces/locations/workspace-location";
+import {
+ parseWorkspaceAddress,
+ resolveWorkspaceAddressLocation,
+} from "#/features/workspaces/locations/workspace-location";
import {
summarizeFlashcardStudyProgress,
type FlashcardStudyState,
} from "#/features/workspaces/flashcards/flashcard-study-state";
-import { sha256Base64UrlText } from "#/lib/binary";
+import {
+ createQuizQuestionRevision,
+ serializeQuizSetToHtml,
+ type QuizQuestion,
+} from "#/features/workspaces/quizzes/quiz-content";
+import {
+ getQuizAnswer,
+ summarizeQuizStudyProgress,
+ type QuizStudyState,
+} from "#/features/workspaces/quizzes/quiz-study-state";
-const maxWorkspaceContentBatchBytes = 2 * 1024 * 1024 + 64 * 1024;
-const targetFlashcardChunkCharacters = 48_000;
+// A context-sized ceiling for one whole read call, not a transport limit: once
+// a call has returned this much content, further requests in it fail fast and
+// say to read fewer units at a time.
+const maxWorkspaceReadCharacters = 200_000;
+const targetEntryChunkCharacters = 48_000;
interface DocumentContentReader {
readHtmlChunk(input: DocumentHtmlChunkReadInput): Promise;
@@ -61,6 +68,12 @@ type FlashcardItemReader = (
| { cards: Flashcard[]; studyState: FlashcardStudyState }
| Promise<{ cards: Flashcard[]; studyState: FlashcardStudyState }>;
+type QuizItemReader = (
+ itemId: string,
+) =>
+ | { questions: QuizQuestion[]; studyState: QuizStudyState }
+ | Promise<{ questions: QuizQuestion[]; studyState: QuizStudyState }>;
+
interface PendingReadyResult {
item: WorkspaceItem;
read: Extract;
@@ -71,90 +84,71 @@ export async function readWorkspaceContent(input: {
bucket: R2Bucket;
getDocumentSession: (itemId: string) => DocumentContentReader | Promise;
readFlashcardItem: FlashcardItemReader;
- resolveReference?: (itemId: string, ref: string) => WorkspaceLocation | undefined;
+ readQuizItem: QuizItemReader;
+ /** Resolves an item address's refKey to a live item and its path. */
+ resolveRefKey: (refKey: string) => Promise<{ item: WorkspaceItem; path: string } | undefined>;
requests: WorkspaceContentReadRequest[];
workspaceId: string;
}): Promise {
const { requests } = input;
- const encoder = new TextEncoder();
- const resolutions = await resolveWorkspacePaths({
- paths: requests.map((request) => request.path),
+ const pathResolutions = await resolveWorkspacePaths({
+ paths: requests.flatMap((request) => ("path" in request ? [request.path] : [])),
workspaceId: input.workspaceId,
});
const results: WorkspaceContentReadResult[] = [];
const readyResults: PendingReadyResult[] = [];
- let returnedContentBytes = 0;
- let readBudgetExhausted = false;
-
- // Reads stay ordered so each body is consumed before the shared byte budget advances.
- for (const [index, resolution] of resolutions.entries()) {
- const request = requests[index];
- if (!request) {
- throw new Error("Workspace content resolution did not match its request.");
- }
- if (resolution.status === "invalid_path") {
- results.push({ code: resolution.code, path: resolution.path, status: "failed" });
- continue;
- }
- if (resolution.status === "root") {
- results.push({ code: "path_is_folder", path: resolution.path, status: "failed" });
- continue;
- }
- if (resolution.status === "not_found") {
- results.push({ code: "path_not_found", path: resolution.path, status: "failed" });
- continue;
- }
- if (isWorkspaceItemContainer(resolution.item.type)) {
- results.push({ code: "path_is_folder", path: resolution.path, status: "failed" });
+ let returnedCharacters = 0;
+ let pathIndex = 0;
+
+ // Reads stay ordered so each body is consumed before the shared budget advances.
+ for (const request of requests) {
+ const resolved =
+ "path" in request
+ ? resolvePathRequest(pathResolutions[pathIndex++], request.path)
+ : await resolveRefRequest(input.resolveRefKey, request.ref);
+ if ("failure" in resolved) {
+ results.push(resolved.failure);
continue;
}
- const readBudgetFailure = {
- code: "read_budget_exceeded" as const,
- path: resolution.path,
- status: "failed" as const,
- ...(getWorkspaceItemContentKind(resolution.item.type) === "file"
- ? { type: "file" as const }
- : {}),
- };
- if (readBudgetExhausted) {
- results.push(readBudgetFailure);
+
+ if (returnedCharacters >= maxWorkspaceReadCharacters) {
+ results.push({
+ code: "read_budget_exceeded",
+ message: "This call already returned as much as fits. Read fewer units per call.",
+ path: resolved.path,
+ status: "failed",
+ });
continue;
}
try {
const read = await readWorkspaceItem({
...input,
- item: resolution.item,
+ item: resolved.item,
request,
- path: resolution.path,
+ path: resolved.path,
});
if (read.status !== "ready") {
results.push(read);
continue;
}
- const contentBytes = encoder.encode(
- "content" in read ? read.content : JSON.stringify(read.cards),
- ).byteLength;
- if (returnedContentBytes + contentBytes > maxWorkspaceContentBatchBytes) {
- readBudgetExhausted = true;
- results.push(readBudgetFailure);
- continue;
- }
- returnedContentBytes += contentBytes;
+ returnedCharacters +=
+ "content" in read
+ ? read.content.length
+ : JSON.stringify("cards" in read ? read.cards : read.questions).length;
- const pending = {
- item: resolution.item,
+ readyResults.push({
+ item: resolved.item,
read,
relations: listWorkspaceItemRelations({
- itemId: resolution.item.id,
+ itemId: resolved.item.id,
workspaceId: input.workspaceId,
}),
- };
- readyResults.push(pending);
+ });
results.push(read);
} catch (error) {
if (error instanceof WorkspacePageSelectionError) {
- results.push({ code: error.code, path: resolution.path, status: "failed" });
+ results.push({ code: error.code, path: resolved.path, status: "failed" });
continue;
}
throw error;
@@ -165,18 +159,52 @@ export async function readWorkspaceContent(input: {
return results;
}
+function resolvePathRequest(
+ resolution: Awaited>[number] | undefined,
+ path: string,
+): { item: WorkspaceItem; path: string } | { failure: WorkspaceContentReadResult } {
+ if (!resolution) {
+ throw new Error("Workspace content resolution did not match its request.");
+ }
+ if (resolution.status === "invalid_path") {
+ return { failure: { code: resolution.code, path: resolution.path, status: "failed" } };
+ }
+ if (resolution.status === "root") {
+ return { failure: { code: "path_is_folder", path: resolution.path, status: "failed" } };
+ }
+ if (resolution.status === "not_found") {
+ return { failure: { code: "path_not_found", path: resolution.path, status: "failed" } };
+ }
+ if (isWorkspaceItemContainer(resolution.item.type)) {
+ return { failure: { code: "path_is_folder", path, status: "failed" } };
+ }
+ return { item: resolution.item, path: resolution.path };
+}
+
+async function resolveRefRequest(
+ resolveRefKey: (refKey: string) => Promise<{ item: WorkspaceItem; path: string } | undefined>,
+ ref: string,
+): Promise<{ item: WorkspaceItem; path: string } | { failure: WorkspaceContentReadResult }> {
+ const address = parseWorkspaceAddress(ref);
+ const resolved = address ? await resolveRefKey(address.refKey) : undefined;
+ if (!resolved || isWorkspaceItemContainer(resolved.item.type)) {
+ return { failure: { code: "ref_not_found", ref, status: "failed" } };
+ }
+ return resolved;
+}
+
async function readWorkspaceItem(input: {
bucket: R2Bucket;
getDocumentSession: (itemId: string) => DocumentContentReader | Promise;
readFlashcardItem: FlashcardItemReader;
- resolveReference?: (itemId: string, ref: string) => WorkspaceLocation | undefined;
+ readQuizItem: QuizItemReader;
item: WorkspaceItem;
path: string;
request: WorkspaceContentReadRequest;
workspaceId: string;
}): Promise {
if (input.request.mode === "ref") {
- return readWorkspaceReference(input, input.request.ref);
+ return readWorkspaceUnit(input, input.request.ref);
}
switch (input.item.type) {
case "document":
@@ -187,36 +215,36 @@ async function readWorkspaceItem(input: {
return { code: "unsupported_item_type", path: input.path, status: "failed" };
case "flashcard":
return readFlashcards(input);
+ case "quiz":
+ return readQuiz(input);
}
}
-async function readWorkspaceReference(
+/** Reads the exact content an address identifies: one page, block, or entry. */
+async function readWorkspaceUnit(
input: Parameters[0],
ref: string,
): Promise {
- const location = input.resolveReference?.(input.item.id, ref);
- if (!location || location.itemId !== input.item.id) {
- return { code: "ref_not_found", path: input.path, status: "failed" };
+ const address = parseWorkspaceAddress(ref);
+ const location = address ? resolveWorkspaceAddressLocation(input.item, address) : undefined;
+ if (!location) {
+ return { code: "ref_not_found", ref, status: "failed" };
}
switch (location.kind) {
case "item":
return readWorkspaceItem({ ...input, request: { mode: "start", path: input.path } });
case "pdf-page":
- return input.item.type === "file"
- ? readFile({
- ...input,
- request: { mode: "pages", path: input.path, range: String(location.pageNumber) },
- })
- : { code: "ref_not_found", path: input.path, status: "failed" };
+ return readFile({
+ ...input,
+ request: { mode: "pages", path: input.path, range: String(location.pageNumber) },
+ });
case "document-block":
- return input.item.type === "document"
- ? readDocumentBlock(input, location.blockId)
- : { code: "ref_not_found", path: input.path, status: "failed" };
+ return readDocumentBlock(input, location.blockId);
case "flashcard":
- return input.item.type === "flashcard"
- ? readFlashcards(input, location.cardId)
- : { code: "ref_not_found", path: input.path, status: "failed" };
+ return readFlashcards(input, location.cardId);
+ case "quiz-question":
+ return readQuiz(input, location.questionId);
}
}
@@ -230,73 +258,23 @@ async function readFlashcards(
},
targetCardId?: string,
): Promise {
- if (
- !targetCardId &&
- input.request.mode !== "start" &&
- input.request.mode !== "continue" &&
- input.request.mode !== "cards"
- ) {
- return { code: "invalid_selection", path: input.path, status: "failed" };
- }
-
const { cards, studyState } = await input.readFlashcardItem(input.item.id);
const cardsById = new Map(cards.map((card) => [card.id, card]));
- const serializedCards = serializeFlashcardSetToHtml({ cards, version: 1 });
- let selectedCards: typeof serializedCards;
- let returned: number[];
- let nextCursor: string | undefined;
-
- if (targetCardId) {
- const cardIndex = serializedCards.findIndex((card) => card.id === targetCardId);
- if (cardIndex < 0) return { code: "ref_not_found", path: input.path, status: "failed" };
- selectedCards = [serializedCards[cardIndex]!];
- returned = [cardIndex + 1];
- } else if (input.request.mode === "cards") {
- try {
- returned = parseWorkspacePageRange(input.request.range, cards.length);
- } catch (error) {
- if (error instanceof WorkspacePageSelectionError) {
- return { code: "invalid_selection", path: input.path, status: "failed" };
- }
- throw error;
- }
- selectedCards = returned.map((cardNumber) => serializedCards[cardNumber - 1]!);
- } else {
- const encodedCursor = input.request.mode === "continue" ? input.request.cursor : undefined;
- const cursor = encodedCursor ? decodeWorkspaceContentCursor(encodedCursor) : undefined;
- if (encodedCursor && (!cursor || cursor.kind !== "flashcard" || cursor.path !== input.path)) {
- return { code: "invalid_cursor", path: input.path, status: "failed" };
- }
-
- const revision = await sha256Base64UrlText(JSON.stringify(cards));
- if (cursor?.kind === "flashcard" && cursor.revision !== revision) {
- return { code: "content_changed", path: input.path, status: "failed" };
- }
-
- const offset = cursor?.kind === "flashcard" ? cursor.offset : 0;
- const chunk = readFlashcardChunk(serializedCards, offset);
- if (!chunk) return { code: "invalid_cursor", path: input.path, status: "failed" };
- selectedCards = chunk.cards;
- returned = Array.from({ length: chunk.endOffset - offset }, (_, index) => offset + index + 1);
- if (chunk.endOffset < cards.length) {
- nextCursor = encodeWorkspaceContentCursor({
- kind: "flashcard",
- offset: chunk.endOffset,
- path: input.path,
- revision,
- version: 1,
- });
- }
- }
+ const selection = selectOrderedEntries({
+ entries: serializeFlashcardSetToHtml({ cards, version: 1 }),
+ measure: (card) => card.front.length + card.back.length,
+ request: input.request,
+ targetEntryId: targetCardId,
+ });
+ if (!selection.ok) return { code: selection.code, path: input.path, status: "failed" };
return {
cards: await Promise.all(
- selectedCards.map(async (card) => {
+ selection.selected.map(async (card) => {
const source = cardsById.get(card.id);
if (!source) throw new Error("Serialized flashcard does not match its source set.");
return {
- cardId: card.id,
- revision: await createFlashcardRevision(source),
+ ref: `${card.id}.r_${await createFlashcardRevision(source)}`,
front: card.front,
back: card.back,
...(studyState.cards[card.id] ? { study: studyState.cards[card.id] } : {}),
@@ -306,35 +284,141 @@ async function readFlashcards(
format: "html",
itemId: input.item.id,
location: {
- kind: "cards",
- returned,
+ kind: "entries",
+ returned: selection.returned,
total: cards.length,
},
- ...(nextCursor ? { nextCursor } : {}),
path: input.path,
progress: summarizeFlashcardStudyProgress(
cards.map((card) => card.id),
studyState,
),
+ ref: input.item.refKey,
status: "ready",
type: "flashcard",
};
}
-function readFlashcardChunk(cards: ReturnType, offset: number) {
- if (offset < 0 || offset >= cards.length) return null;
+async function readQuiz(
+ input: {
+ item: WorkspaceItem;
+ path: string;
+ readQuizItem: QuizItemReader;
+ request: WorkspaceContentReadRequest;
+ workspaceId: string;
+ },
+ targetQuestionId?: string,
+): Promise {
+ const { questions, studyState } = await input.readQuizItem(input.item.id);
+ const questionsById = new Map(questions.map((question) => [question.id, question]));
+ const selection = selectOrderedEntries({
+ entries: serializeQuizSetToHtml({ questions, version: 1 }),
+ measure: (question) =>
+ question.question.length +
+ question.explanation.length +
+ question.options.reduce((total, option) => total + option.text.length, 0),
+ request: input.request,
+ targetEntryId: targetQuestionId,
+ });
+ if (!selection.ok) return { code: selection.code, path: input.path, status: "failed" };
+
+ return {
+ format: "html",
+ itemId: input.item.id,
+ location: {
+ kind: "entries",
+ returned: selection.returned,
+ total: questions.length,
+ },
+ path: input.path,
+ progress: summarizeQuizStudyProgress(questions, studyState),
+ questions: await Promise.all(
+ selection.selected.map(async (question) => {
+ const source = questionsById.get(question.id);
+ if (!source) throw new Error("Serialized quiz question does not match its source set.");
+ const answer = getQuizAnswer(source, studyState);
+ const selectedIndex = answer
+ ? source.options.findIndex((option) => option.id === answer.selectedOptionId)
+ : -1;
+ return {
+ ref: `${question.id}.r_${await createQuizQuestionRevision(source)}`,
+ question: question.question,
+ options: question.options.map(({ text, correct }) => ({ text, correct })),
+ explanation: question.explanation,
+ ...(answer && selectedIndex >= 0
+ ? {
+ answer: {
+ selected: selectedIndex + 1,
+ correct: answer.selectedOptionId === source.correctOptionId,
+ },
+ }
+ : {}),
+ };
+ }),
+ ),
+ ref: input.item.refKey,
+ status: "ready",
+ type: "quiz",
+ };
+}
+
+type OrderedEntrySelection =
+ | { ok: true; selected: T[]; returned: number[] }
+ | { ok: false; code: "invalid_selection" | "ref_not_found" };
+
+/**
+ * Shared selection for structured items: one targeted entry from an address,
+ * an explicit entry range, or the first character-budgeted chunk on `start`.
+ * Every result names the entry numbers it covered, so continuing is just the
+ * next range — no cursor to carry.
+ */
+function selectOrderedEntries(input: {
+ entries: T[];
+ measure: (entry: T) => number;
+ request: WorkspaceContentReadRequest;
+ targetEntryId?: string;
+}): OrderedEntrySelection {
+ const { entries, request, targetEntryId } = input;
+
+ if (targetEntryId) {
+ const entryIndex = entries.findIndex((entry) => entry.id === targetEntryId);
+ if (entryIndex < 0) return { ok: false, code: "ref_not_found" };
+ return { ok: true, selected: [entries[entryIndex]!], returned: [entryIndex + 1] };
+ }
+ if (request.mode === "entries") {
+ let returned: number[];
+ try {
+ returned = parseWorkspacePageRange(request.range, entries.length);
+ } catch (error) {
+ if (error instanceof WorkspacePageSelectionError) {
+ return { ok: false, code: "invalid_selection" };
+ }
+ throw error;
+ }
+ return {
+ ok: true,
+ selected: returned.map((entryNumber) => entries[entryNumber - 1]!),
+ returned,
+ };
+ }
+ if (request.mode !== "start") {
+ return { ok: false, code: "invalid_selection" };
+ }
let characters = 0;
- let endOffset = offset;
- while (endOffset < cards.length) {
- const card = cards[endOffset]!;
- const cardCharacters = card.front.length + card.back.length;
- if (endOffset > offset && characters + cardCharacters > targetFlashcardChunkCharacters) break;
- characters += cardCharacters;
+ let endOffset = 0;
+ while (endOffset < entries.length) {
+ const entryCharacters = input.measure(entries[endOffset]!);
+ if (endOffset > 0 && characters + entryCharacters > targetEntryChunkCharacters) break;
+ characters += entryCharacters;
endOffset += 1;
}
- return { cards: cards.slice(offset, endOffset), endOffset };
+ return {
+ ok: true,
+ selected: entries.slice(0, endOffset),
+ returned: Array.from({ length: endOffset }, (_, index) => index + 1),
+ };
}
/**
@@ -364,6 +448,7 @@ async function readDocumentBlock(
format: "html",
itemId: input.item.id,
path: input.path,
+ ref: input.item.refKey,
status: "ready",
type: "block",
};
@@ -376,26 +461,31 @@ async function readDocument(input: {
request: WorkspaceContentReadRequest;
workspaceId: string;
}): Promise {
- if (input.request.mode !== "start" && input.request.mode !== "continue") {
+ let chunkInput: DocumentHtmlChunkReadInput;
+ if (input.request.mode === "start") {
+ chunkInput = { offset: 0 };
+ } else if (input.request.mode === "entries") {
+ // Blocks are contiguous prose; a scattered range has no meaningful join.
+ const range = /^(\d+)(?:\s*-\s*(\d+))?$/.exec(input.request.range);
+ const startBlock = range ? Number(range[1]) : 0;
+ const endBlock = range?.[2] ? Number(range[2]) : startBlock;
+ if (!range || startBlock < 1 || endBlock < startBlock) {
+ return {
+ code: "invalid_selection",
+ message: "Document entries must be one block number or one contiguous range like 5-12.",
+ path: input.path,
+ status: "failed",
+ };
+ }
+ chunkInput = { offset: startBlock - 1, maxBlocks: endBlock - startBlock + 1 };
+ } else {
return { code: "invalid_selection", path: input.path, status: "failed" };
}
- const encodedCursor = input.request.mode === "continue" ? input.request.cursor : undefined;
- const cursor = encodedCursor ? decodeWorkspaceContentCursor(encodedCursor) : undefined;
- if (encodedCursor && (!cursor || cursor.kind !== "document" || cursor.path !== input.path)) {
- return { code: "invalid_cursor", path: input.path, status: "failed" };
- }
-
const documentSession = await input.getDocumentSession(input.item.id);
- const chunk = await documentSession.readHtmlChunk({
- expectedRevision: cursor?.kind === "document" ? cursor.revision : undefined,
- offset: cursor?.kind === "document" ? cursor.offset : 0,
- });
- if (chunk.status === "content_changed") {
- return { code: "content_changed", path: input.path, status: "failed" };
- }
+ const chunk = await documentSession.readHtmlChunk(chunkInput);
if (chunk.status === "invalid_offset") {
- return { code: "invalid_cursor", path: input.path, status: "failed" };
+ return { code: "invalid_selection", path: input.path, status: "failed" };
}
return {
@@ -403,18 +493,8 @@ async function readDocument(input: {
format: "html",
itemId: input.item.id,
location: { kind: "blocks", ...chunk.location },
- ...(chunk.nextOffset === undefined
- ? {}
- : {
- nextCursor: encodeWorkspaceContentCursor({
- kind: "document",
- offset: chunk.nextOffset,
- path: input.path,
- revision: chunk.revision,
- version: 3,
- }),
- }),
path: input.path,
+ ref: input.item.refKey,
status: "ready",
type: "document",
};
@@ -427,11 +507,7 @@ async function readFile(input: {
request: WorkspaceContentReadRequest;
workspaceId: string;
}): Promise {
- if (
- input.request.mode !== "start" &&
- input.request.mode !== "continue" &&
- input.request.mode !== "pages"
- ) {
+ if (input.request.mode !== "start" && input.request.mode !== "pages") {
return { code: "invalid_selection", path: input.path, status: "failed" };
}
const fileType = resolveWorkspaceFileTypeFromItem(input.item);
@@ -450,25 +526,12 @@ async function readFile(input: {
return describeUnreadableProjection(projection, input.path, input.item.id);
}
- const encodedCursor = input.request.mode === "continue" ? input.request.cursor : undefined;
- const cursor = encodedCursor ? decodeWorkspaceContentCursor(encodedCursor) : undefined;
- if (encodedCursor && (!cursor || cursor.kind !== "file" || cursor.path !== input.path)) {
- return { code: "invalid_cursor", path: input.path, status: "failed" };
- }
- if (cursor?.kind === "file" && cursor.sourceHash !== projection.sourceHash) {
- return { code: "content_changed", path: input.path, status: "failed" };
- }
let pageRead: Awaited>;
try {
pageRead = await readWorkspacePageProjection({
itemId: input.item.id,
pageCount: projection.pageCount,
- pages:
- cursor?.kind === "file"
- ? String(cursor.nextPage)
- : input.request.mode === "pages"
- ? input.request.range
- : undefined,
+ pages: input.request.mode === "pages" ? input.request.range : undefined,
workspaceId: input.workspaceId,
});
} catch (error) {
@@ -477,7 +540,6 @@ async function readFile(input: {
}
return { code: "projection_failed", path: input.path, status: "failed", type: "file" };
}
- const nextPage = Math.max(...pageRead.pages.returned) + 1;
return {
assetKind: fileType.assetKind,
content: pageRead.content,
@@ -485,19 +547,9 @@ async function readFile(input: {
format: "markdown",
itemId: input.item.id,
location: { kind: "pages", ...pageRead.pages },
- ...(nextPage > pageRead.pages.total
- ? {}
- : {
- nextCursor: encodeWorkspaceContentCursor({
- kind: "file",
- nextPage,
- path: input.path,
- sourceHash: projection.sourceHash,
- version: 2,
- }),
- }),
path: input.path,
...(projection.provisional ? { provisional: true } : {}),
+ ref: input.item.refKey,
status: "ready",
type: "file",
};
diff --git a/src/features/workspaces/content/workspace-read-model-output.test.ts b/src/features/workspaces/content/workspace-read-model-output.test.ts
new file mode 100644
index 00000000..47ffdbcd
--- /dev/null
+++ b/src/features/workspaces/content/workspace-read-model-output.test.ts
@@ -0,0 +1,83 @@
+import { describe, expect, it } from "vitest";
+
+import type { WorkspaceReadItemsOutput } from "#/features/workspaces/content/workspace-content-contract";
+import { createWorkspaceReadItemsModelOutput } from "#/features/workspaces/content/workspace-read-model-output";
+
+describe("workspace read model output", () => {
+ it("drops internal item ids and keeps self-describing refs", () => {
+ const output: WorkspaceReadItemsOutput = {
+ results: [
+ {
+ content: 'Notes
',
+ format: "html",
+ itemId: "document-1",
+ location: { endBlock: 1, kind: "blocks", startBlock: 1, totalBlocks: 1 },
+ path: "/Notes",
+ ref: "Xk7p2Qa9",
+ status: "ready",
+ type: "document",
+ },
+ ],
+ };
+
+ const modelOutput = createWorkspaceReadItemsModelOutput(output);
+ expect(modelOutput).not.toHaveProperty("guidance");
+ expect(modelOutput.results[0]).toMatchObject({
+ content: expect.stringContaining('data-ref="b_abcdefghijkl.r_012345"'),
+ path: "/Notes",
+ ref: "Xk7p2Qa9",
+ status: "ready",
+ });
+ expect(JSON.stringify(modelOutput)).not.toContain("document-1");
+ });
+
+ it("emits each handling guidance once per situation", () => {
+ const output: WorkspaceReadItemsOutput = {
+ results: [
+ {
+ elapsedSeconds: 5,
+ path: "/A.pdf",
+ phase: "extracting",
+ retryAfterSeconds: 10,
+ status: "pending",
+ type: "file",
+ },
+ {
+ elapsedSeconds: 9,
+ path: "/B.pdf",
+ phase: "queued",
+ retryAfterSeconds: 10,
+ status: "pending",
+ type: "file",
+ },
+ { code: "extraction_failed", path: "/C.pdf", status: "failed", type: "file" },
+ ],
+ };
+
+ const modelOutput = createWorkspaceReadItemsModelOutput(output);
+ expect(modelOutput.guidance).toHaveLength(2);
+ expect(modelOutput.guidance?.[0]).toContain("still extracting");
+ expect(modelOutput.guidance?.[1]).toContain("will not finish");
+ });
+
+ it("does not warn about empty pages once extraction is final", () => {
+ const output: WorkspaceReadItemsOutput = {
+ results: [
+ {
+ assetKind: "pdf",
+ content: "## Page 1",
+ emptyPages: [1],
+ format: "markdown",
+ itemId: "file-1",
+ location: { kind: "pages", requested: "1", returned: [1], total: 1 },
+ path: "/Book.pdf",
+ ref: "Yk7p2Qa9",
+ status: "ready",
+ type: "file",
+ },
+ ],
+ };
+
+ expect(createWorkspaceReadItemsModelOutput(output)).not.toHaveProperty("guidance");
+ });
+});
diff --git a/src/features/workspaces/content/workspace-read-model-output.ts b/src/features/workspaces/content/workspace-read-model-output.ts
new file mode 100644
index 00000000..9bf10023
--- /dev/null
+++ b/src/features/workspaces/content/workspace-read-model-output.ts
@@ -0,0 +1,81 @@
+import type {
+ WorkspaceContentReadResult,
+ WorkspaceReadItemsOutput,
+} from "#/features/workspaces/content/workspace-content-contract";
+
+/**
+ * Guidance for read outcomes the model has to react to, keyed by situation.
+ *
+ * These live here rather than in the tool description because none of them
+ * change how a read is issued, and background extraction states are rare enough
+ * that every request should not carry the instructions for handling them.
+ */
+const workspaceReadGuidance = {
+ pending:
+ "Some paths are still extracting. Never sleep, poll, or otherwise stall waiting for them, including inside compute, sandbox_bash, or orchestrate. If an original file is attached, use it and do not read that path again in this reply. Otherwise, either do other work and read pending paths again later in this reply, or tell the user they are still processing and to ask again in about retryAfterSeconds. Never read the same pending path more than twice in one reply.",
+ unrecoverable:
+ "Extraction will not finish for some paths. Report the code and any message to the user; do not retry those reads and do not suggest re-uploading the file.",
+ transient:
+ "Some paths failed on a transient storage problem. One repeat read is reasonable; if it fails again, tell the user.",
+ provisional:
+ "Some content came from a fast first pass. Pages listed in emptyPages are still extracting, so read them again later rather than reporting them as blank.",
+} as const;
+
+/**
+ * Collects the handling guidance a set of read results calls for.
+ *
+ * Emitted once per situation rather than once per result so a batch of pending
+ * reads does not repeat the same paragraph for every path.
+ */
+function createWorkspaceReadGuidance(results: readonly WorkspaceContentReadResult[]): string[] {
+ const situations = new Set();
+
+ for (const result of results) {
+ if (result.status === "pending") {
+ situations.add("pending");
+ continue;
+ }
+
+ if (result.status === "failed") {
+ if (result.code === "extraction_failed" || result.code === "extraction_stalled") {
+ situations.add("unrecoverable");
+ } else if (result.code === "projection_failed") {
+ situations.add("transient");
+ }
+ continue;
+ }
+
+ // Gate on provisional only: emptyPages on a final (non-provisional) read
+ // describes genuinely blank pages, which must not be reported as still
+ // extracting or the model retries a completed read forever.
+ if (result.type === "file" && result.provisional) {
+ situations.add("provisional");
+ }
+ }
+
+ return (Object.keys(workspaceReadGuidance) as Array)
+ .filter((situation) => situations.has(situation))
+ .map((situation) => workspaceReadGuidance[situation]);
+}
+
+/**
+ * Projects a rich workspace read result into the model-visible JSON.
+ *
+ * The results already carry self-describing addresses, so the only work left
+ * is dropping the internal item id and attaching guidance for outcomes that
+ * need handling.
+ */
+export function createWorkspaceReadItemsModelOutput(output: WorkspaceReadItemsOutput) {
+ const guidance = createWorkspaceReadGuidance(output.results);
+
+ return {
+ ...(guidance.length > 0 ? { guidance } : {}),
+ results: output.results.map(omitWorkspaceReadItemId),
+ };
+}
+
+function omitWorkspaceReadItemId(result: T): Omit {
+ const { itemId: _itemId, ...modelResult } = result as T & { itemId?: string };
+
+ return modelResult;
+}
diff --git a/src/features/workspaces/content/workspace-read-references.test.ts b/src/features/workspaces/content/workspace-read-references.test.ts
deleted file mode 100644
index 4fca8c2d..00000000
--- a/src/features/workspaces/content/workspace-read-references.test.ts
+++ /dev/null
@@ -1,274 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import type {
- WorkspaceContentReadResult,
- WorkspaceReadItemsOutput,
-} from "#/features/workspaces/content/workspace-content-contract";
-import {
- createWorkspaceReadItemsModelOutput,
- createWorkspaceReadReferences,
-} from "#/features/workspaces/content/workspace-read-references";
-
-describe("workspace read references", () => {
- it("gives document blocks and extracted pages one transcript-backed ref each", () => {
- const results = [documentResult(), fileResult()] satisfies WorkspaceContentReadResult[];
- const references = createWorkspaceReadReferences(results);
-
- expect(references).toHaveLength(3);
- expect(references.map(({ location }) => location)).toEqual([
- {
- blockId: "b_abcdefghijkl",
- itemId: "document-1",
- kind: "document-block",
- version: 1,
- },
- { itemId: "file-1", kind: "pdf-page", pageNumber: 12, version: 1 },
- { itemId: "file-1", kind: "pdf-page", pageNumber: 13, version: 1 },
- ]);
- expect(references.every(({ ref }) => /^wr_[0-9A-Za-z]{8}$/.test(ref))).toBe(true);
- });
-
- it("projects refs beside content without exposing durable item IDs", () => {
- const results = [documentResult(), fileResult()] satisfies WorkspaceContentReadResult[];
- const output: WorkspaceReadItemsOutput = {
- references: createWorkspaceReadReferences(results),
- results,
- };
- const modelOutput = createWorkspaceReadItemsModelOutput(output);
- const document = modelOutput.results[0];
- const file = modelOutput.results[1];
-
- expect(document).toMatchObject({
- content: expect.stringMatching(/data-ref="wr_[0-9A-Za-z]{8}"/),
- path: "/Notes",
- status: "ready",
- type: "document",
- });
- expect(file).toMatchObject({
- status: "ready",
- type: "file",
- });
- expect(file).not.toHaveProperty("pageReferences");
- expect(file && "content" in file ? file.content : "").toMatch(
- /^## Page 12 \[ref: wr_[0-9A-Za-z]{8}\]$/m,
- );
- expect(file && "content" in file ? file.content : "").toMatch(
- /^## Page 13 \[ref: wr_[0-9A-Za-z]{8}\]$/m,
- );
- expect(JSON.stringify(modelOutput)).not.toContain("document-1");
- expect(JSON.stringify(modelOutput)).not.toContain("file-1");
- });
-
- it("gives each flashcard one ref for editing, citation, and navigation", () => {
- const results = [flashcardResult()] satisfies WorkspaceContentReadResult[];
- const references = createWorkspaceReadReferences(results);
- const modelOutput = createWorkspaceReadItemsModelOutput({ references, results });
-
- expect(references.map(({ location }) => location)).toEqual([
- {
- cardId: "f67080f9-0158-4565-86a9-4c90ed6809d2",
- itemId: "flashcard-1",
- kind: "flashcard",
- version: 1,
- },
- ]);
- expect(modelOutput.results[0]).toMatchObject({
- cards: [
- {
- back: "Paris
",
- front: "Capital of France?
",
- ref: expect.stringMatching(/^wr_[0-9A-Za-z]{8}$/),
- },
- ],
- path: "/Geography",
- progress: { gotItCount: 1, missedCount: 0, reviewedCount: 1 },
- type: "flashcard",
- });
- expect(JSON.stringify(modelOutput)).not.toContain("flashcard-1");
- });
-
- it("deduplicates repeated reads of the same durable location in one result", () => {
- const references = createWorkspaceReadReferences([
- documentResult(),
- { ...documentResult(), content: "continued" },
- ]);
-
- expect(references).toHaveLength(1);
- });
-
- it("uses an item ref for extracted images that have no page-navigation surface", () => {
- const image = {
- ...fileResult(),
- assetKind: "image",
- itemId: "image-1",
- path: "/Diagram.png",
- } satisfies Extract;
- const references = createWorkspaceReadReferences([image]);
- const modelOutput = createWorkspaceReadItemsModelOutput({
- references,
- results: [image],
- });
-
- expect(references).toMatchObject([
- { location: { itemId: "image-1", kind: "item", version: 1 } },
- ]);
- expect(modelOutput.results[0]).toMatchObject({
- assetKind: "image",
- ref: expect.stringMatching(/^wr_[0-9A-Za-z]{8}$/),
- });
- expect(modelOutput.results[0]).not.toHaveProperty("pageReferences");
- });
-
- it("stays silent when every read succeeded outright", () => {
- const results = [documentResult(), fileResult()] satisfies WorkspaceContentReadResult[];
-
- expect(
- createWorkspaceReadItemsModelOutput({
- references: createWorkspaceReadReferences(results),
- results,
- }),
- ).not.toHaveProperty("guidance");
- });
-
- it("explains a pending read once however many paths are waiting", () => {
- const results = [
- {
- elapsedSeconds: 4,
- itemId: "file-a",
- path: "/A.pdf",
- phase: "extracting",
- retryAfterSeconds: 15,
- status: "pending",
- type: "file",
- },
- {
- elapsedSeconds: 0,
- path: "/B.pdf",
- phase: "queued",
- retryAfterSeconds: 15,
- status: "pending",
- type: "file",
- },
- ] satisfies WorkspaceContentReadResult[];
- const modelOutput = createWorkspaceReadItemsModelOutput({ references: [], results });
- const { guidance } = modelOutput;
-
- expect(guidance).toHaveLength(1);
- expect(guidance?.[0]).toContain("Never sleep");
- expect(JSON.stringify(modelOutput)).not.toContain("file-a");
- });
-
- it("separates failures that will never resolve from transient ones", () => {
- const results = [
- { code: "extraction_failed", path: "/A.pdf", status: "failed", type: "file" },
- { code: "extraction_stalled", path: "/B.pdf", status: "failed", type: "file" },
- { code: "projection_failed", path: "/C.pdf", status: "failed", type: "file" },
- ] satisfies WorkspaceContentReadResult[];
- const guidance = createWorkspaceReadItemsModelOutput({ references: [], results }).guidance;
-
- expect(guidance).toHaveLength(2);
- expect(guidance?.[0]).toContain("do not suggest re-uploading");
- expect(guidance?.[1]).toContain("One repeat read is reasonable");
- });
-
- it("says nothing about failures that are the caller's own mistake", () => {
- const results = [
- { code: "path_not_found", path: "/Missing.pdf", status: "failed" },
- ] satisfies WorkspaceContentReadResult[];
-
- expect(createWorkspaceReadItemsModelOutput({ references: [], results })).not.toHaveProperty(
- "guidance",
- );
- });
-
- it("warns that blank pages from the fast pass are not final", () => {
- const results = [
- { ...fileResult(), emptyPages: [13], provisional: true },
- ] satisfies WorkspaceContentReadResult[];
- const guidance = createWorkspaceReadItemsModelOutput({
- references: createWorkspaceReadReferences(results),
- results,
- }).guidance;
-
- expect(guidance).toHaveLength(1);
- expect(guidance?.[0]).toContain("still extracting");
- });
-
- it("stays silent about blank pages on a final, non-provisional read", () => {
- const results = [{ ...fileResult(), emptyPages: [13] }] satisfies WorkspaceContentReadResult[];
-
- expect(
- createWorkspaceReadItemsModelOutput({
- references: createWorkspaceReadReferences(results),
- results,
- }),
- ).not.toHaveProperty("guidance");
- });
-});
-
-function documentResult(): Extract<
- WorkspaceContentReadResult,
- { status: "ready"; type: "document" }
-> {
- return {
- content: 'Notes
',
- format: "html",
- itemId: "document-1",
- location: { endBlock: 1, kind: "blocks", startBlock: 1, totalBlocks: 1 },
- path: "/Notes",
- status: "ready",
- type: "document",
- };
-}
-
-function fileResult(): Extract {
- return {
- assetKind: "pdf",
- content: "## Page 12\n\nAlpha\n\n## Page 13\n\nBeta",
- format: "markdown",
- itemId: "file-1",
- location: {
- kind: "pages",
- requested: "12-13",
- returned: [12, 13],
- total: 20,
- },
- path: "/Book.pdf",
- status: "ready",
- type: "file",
- };
-}
-
-function flashcardResult(): Extract<
- WorkspaceContentReadResult,
- { status: "ready"; type: "flashcard" }
-> {
- return {
- cards: [
- {
- back: "Paris
",
- cardId: "f67080f9-0158-4565-86a9-4c90ed6809d2",
- revision: "0123456789",
- front: "Capital of France?
",
- study: {
- lastRating: "good",
- lastReviewedAt: "2026-08-13T12:00:00.000Z",
- reviewCount: 1,
- },
- },
- ],
- format: "html",
- itemId: "flashcard-1",
- location: { kind: "cards", returned: [1], total: 1 },
- path: "/Geography",
- progress: {
- gotItCount: 1,
- missedCount: 0,
- reviewedCount: 1,
- totalCards: 1,
- unreviewedCount: 0,
- },
- status: "ready",
- type: "flashcard",
- };
-}
diff --git a/src/features/workspaces/content/workspace-read-references.ts b/src/features/workspaces/content/workspace-read-references.ts
deleted file mode 100644
index 29cf6ad9..00000000
--- a/src/features/workspaces/content/workspace-read-references.ts
+++ /dev/null
@@ -1,268 +0,0 @@
-import {
- createWorkspaceReferenceRecords,
- getWorkspaceLocationKey,
- type WorkspaceLocation,
- type WorkspaceReference,
- type WorkspaceReferenceRecord,
-} from "#/features/workspaces/locations/workspace-location";
-import {
- parseDocumentAiRef,
- readDocumentAiRefs,
- readDocumentAiRefRevision,
-} from "#/features/workspaces/documents/document-ai-html";
-import type {
- WorkspaceContentReadResult,
- WorkspaceReadItemsOutput,
-} from "#/features/workspaces/content/workspace-content-contract";
-
-/**
- * Allocates durable-location records for every ready workspace read.
- *
- * Editable blocks and cards retain a revision with their durable location.
- * PDFs receive one location per physical page; other files use the item.
- *
- * @param results - Ordered workspace read results.
- * @returns Deduplicated reference records for the rich tool result.
- */
-export function createWorkspaceReadReferences(
- results: readonly WorkspaceContentReadResult[],
-): WorkspaceReferenceRecord[] {
- const targets: Array = [];
-
- for (const result of results) {
- if (result.status !== "ready") {
- continue;
- }
- if (result.type === "flashcard") {
- for (const card of result.cards) {
- targets.push({
- location: {
- itemId: result.itemId,
- kind: "flashcard",
- cardId: card.cardId,
- version: 1,
- },
- revision: card.revision,
- });
- }
- continue;
- }
- if (result.type === "document" || result.type === "block") {
- const contentRefs =
- result.type === "block" ? [result.contentRef] : readDocumentAiRefs(result.content);
- for (const contentRef of contentRefs) {
- const blockId = parseDocumentAiRef(contentRef);
- const revision = readDocumentAiRefRevision(contentRef);
- if (!blockId || !revision)
- throw new Error("Document read returned an invalid content ref.");
- targets.push({
- location: { blockId, itemId: result.itemId, kind: "document-block", version: 1 },
- revision,
- });
- }
- continue;
- }
-
- if (result.type !== "file" || result.assetKind !== "pdf") {
- targets.push({
- itemId: result.itemId,
- kind: "item",
- version: 1,
- });
- continue;
- }
-
- for (const pageNumber of result.location.returned) {
- targets.push({
- itemId: result.itemId,
- kind: "pdf-page",
- pageNumber,
- version: 1,
- });
- }
- }
-
- return createWorkspaceReferenceRecords(targets);
-}
-
-/**
- * Guidance for read outcomes the model has to react to, keyed by situation.
- *
- * These live here rather than in the tool description because none of them
- * change how a read is issued, and background extraction states are rare enough
- * that every request should not carry the instructions for handling them.
- */
-const workspaceReadGuidance = {
- pending:
- "Some paths are still extracting. Never sleep, poll, or otherwise stall waiting for them, including inside compute, sandbox_bash, or orchestrate. If an original file is attached, use it and do not read that path again in this reply. Otherwise, either do other work and read pending paths again later in this reply, or tell the user they are still processing and to ask again in about retryAfterSeconds. Never read the same pending path more than twice in one reply.",
- unrecoverable:
- "Extraction will not finish for some paths. Report the code and any message to the user; do not retry those reads and do not suggest re-uploading the file.",
- transient:
- "Some paths failed on a transient storage problem. One repeat read is reasonable; if it fails again, tell the user.",
- provisional:
- "Some content came from a fast first pass. Pages listed in emptyPages are still extracting, so read them again later rather than reporting them as blank.",
-} as const;
-
-/**
- * Collects the handling guidance a set of read results calls for.
- *
- * Emitted once per situation rather than once per result so a batch of pending
- * reads does not repeat the same paragraph for every path.
- *
- * @param results - Ordered workspace read results.
- * @returns Guidance lines for the situations present, most actionable first.
- */
-function createWorkspaceReadGuidance(results: readonly WorkspaceContentReadResult[]): string[] {
- const situations = new Set();
-
- for (const result of results) {
- if (result.status === "pending") {
- situations.add("pending");
- continue;
- }
-
- if (result.status === "failed") {
- if (result.code === "extraction_failed" || result.code === "extraction_stalled") {
- situations.add("unrecoverable");
- } else if (result.code === "projection_failed") {
- situations.add("transient");
- }
- continue;
- }
-
- // Gate on provisional only: emptyPages on a final (non-provisional) read
- // describes genuinely blank pages, which must not be reported as still
- // extracting or the model retries a completed read forever.
- if (result.type === "file" && result.provisional) {
- situations.add("provisional");
- }
- }
-
- return (Object.keys(workspaceReadGuidance) as Array)
- .filter((situation) => situations.has(situation))
- .map((situation) => workspaceReadGuidance[situation]);
-}
-
-/**
- * Projects a rich workspace read result into compact model-visible JSON.
- *
- * Raw item IDs and durable locations remain in the persisted tool result.
- * Model-visible content receives only opaque refs next to the content they
- * identify, plus guidance for any outcome that needs handling.
- *
- * @param output - Validated rich workspace read output.
- * @returns JSON-safe results annotated with short workspace refs.
- */
-export function createWorkspaceReadItemsModelOutput(output: WorkspaceReadItemsOutput) {
- const refsByLocation = new Map(
- output.references.map((record) => [getWorkspaceLocationKey(record.location), record.ref]),
- );
- const refFor = (location: WorkspaceLocation) =>
- refsByLocation.get(getWorkspaceLocationKey(location));
- const guidance = createWorkspaceReadGuidance(output.results);
-
- return {
- ...(guidance.length > 0 ? { guidance } : {}),
- results: output.results.map((result) => {
- if (result.status === "pending") {
- return omitWorkspaceReadItemId(result);
- }
-
- if (result.status === "failed") {
- return result;
- }
- if (result.type === "flashcard") {
- return {
- ...omitWorkspaceReadItemId(result),
- cards: result.cards.map(({ cardId, revision: _revision, ...card }) => ({
- ...card,
- ref: refFor({ itemId: result.itemId, kind: "flashcard", cardId, version: 1 }),
- })),
- };
- }
- if (result.type === "document") {
- return {
- ...omitWorkspaceReadItemId(result),
- content: replaceDocumentContentRefs(result, refsByLocation),
- };
- }
- if (result.type === "block") {
- const blockId = parseDocumentAiRef(result.contentRef);
- const ref = blockId
- ? refFor({ blockId, itemId: result.itemId, kind: "document-block", version: 1 })
- : undefined;
- const { contentRef: _contentRef, itemId: _itemId, ...modelResult } = result;
- return { ...modelResult, ...(ref ? { ref } : {}) };
- }
-
- if (result.type !== "file" || result.assetKind !== "pdf") {
- const ref = refFor({ itemId: result.itemId, kind: "item", version: 1 });
-
- return {
- ...omitWorkspaceReadItemId(result),
- ...(ref ? { ref } : {}),
- };
- }
-
- const references = result.location.returned.flatMap((pageNumber) => {
- const ref = refFor({
- itemId: result.itemId,
- kind: "pdf-page",
- pageNumber,
- version: 1,
- });
-
- return ref ? [{ pageNumber, ref }] : [];
- });
-
- return {
- ...omitWorkspaceReadItemId(result),
- content: annotateWorkspaceReadPageHeadings(result.content, references),
- };
- }),
- };
-}
-
-function replaceDocumentContentRefs(
- result: Extract,
- refsByLocation: ReadonlyMap,
-) {
- return result.content.replace(/data-ref="([^"]+)"/g, (attribute, contentRef: string) => {
- const blockId = parseDocumentAiRef(contentRef);
- if (!blockId) return attribute;
- const ref = refsByLocation.get(
- getWorkspaceLocationKey({
- blockId,
- itemId: result.itemId,
- kind: "document-block",
- version: 1,
- }),
- );
- return ref ? `data-ref="${ref}"` : attribute;
- });
-}
-
-function omitWorkspaceReadItemId(
- result: T,
-): Omit {
- const { itemId: _itemId, ...modelResult } = result;
-
- return modelResult;
-}
-
-function annotateWorkspaceReadPageHeadings(
- content: string,
- references: readonly { readonly pageNumber: number; readonly ref: WorkspaceReference }[],
-) {
- const refsByPage = new Map(references.map(({ pageNumber, ref }) => [pageNumber, ref]));
-
- return content.replace(/^## Page (\d+)[ \t]*$/gm, (heading, pageNumberText: string) => {
- const pageNumber = Number(pageNumberText);
- const ref = refsByPage.get(pageNumber);
- if (!ref) {
- return heading;
- }
-
- return `${heading} [ref: ${ref}]`;
- });
-}
diff --git a/src/features/workspaces/documents/document-ai-edits.test.ts b/src/features/workspaces/documents/document-ai-edits.test.ts
index b96e55cb..ff169c92 100644
--- a/src/features/workspaces/documents/document-ai-edits.test.ts
+++ b/src/features/workspaces/documents/document-ai-edits.test.ts
@@ -103,7 +103,7 @@ describe("document AI edits", () => {
expect(rewritten.document.content?.at(-1)).toMatchObject({ type: "paragraph" });
expect(await serializeTiptapDocumentToAiHtml(rewritten.document)).toMatch(
- /<\/ul><\/p>$/,
+ /<\/ul>
<\/p>$/,
);
});
diff --git a/src/features/workspaces/documents/document-ai-edits.ts b/src/features/workspaces/documents/document-ai-edits.ts
index ce6b67fa..56dc7e6b 100644
--- a/src/features/workspaces/documents/document-ai-edits.ts
+++ b/src/features/workspaces/documents/document-ai-edits.ts
@@ -19,9 +19,9 @@ import {
type TiptapDocumentJson,
} from "#/features/workspaces/documents/tiptap-document";
import { getTiptapDocumentSchema } from "#/features/workspaces/documents/tiptap-schema";
-import { workspaceReferenceInputSchema } from "#/features/workspaces/locations/workspace-location";
+import { workspaceUnitRefInputSchema } from "#/features/workspaces/locations/workspace-location";
-const documentRefSchema = workspaceReferenceInputSchema.describe(
+const documentRefSchema = workspaceUnitRefInputSchema.describe(
"Exact ref from a recent document or block read.",
);
export const documentAiHtmlSchema = z
diff --git a/src/features/workspaces/documents/document-ai-html.test.ts b/src/features/workspaces/documents/document-ai-html.test.ts
index ffa56fc4..06c3fc0e 100644
--- a/src/features/workspaces/documents/document-ai-html.test.ts
+++ b/src/features/workspaces/documents/document-ai-html.test.ts
@@ -19,7 +19,7 @@ describe("document AI HTML", () => {
).document;
const html = await serializeTiptapDocumentToAiHtml(document);
- expect(html).toMatch(/^
Notes<\/h1>/);
+ expect(html).toMatch(/^Notes<\/h1>/);
expect(html).toContain("bold");
expect(html).toContain('data-type="inline-math"');
expect(html).toContain('data-type="taskItem"');
@@ -47,7 +47,7 @@ describe("document AI HTML", () => {
);
expect(html).not.toContain("b_modelchosen1");
- expect(html).toMatch(/data-ref="b_[A-Za-z0-9_-]{12}\.r_[A-Za-z0-9_-]{10}"/);
+ expect(html).toMatch(/data-ref="b_[A-Za-z0-9_-]{12}\.r_[A-Za-z0-9_-]{6}"/);
});
it("normalizes malformed but recoverable HTML", () => {
diff --git a/src/features/workspaces/documents/document-ai-html.ts b/src/features/workspaces/documents/document-ai-html.ts
index cb22531a..6eeafeff 100644
--- a/src/features/workspaces/documents/document-ai-html.ts
+++ b/src/features/workspaces/documents/document-ai-html.ts
@@ -16,7 +16,7 @@ import { sha256Base64UrlText } from "#/lib/binary";
const TEXT_NODE = 3;
const documentBlockIdPattern = /^b_[A-Za-z0-9_-]{12}$/;
-const documentAiRefPattern = /^(b_[A-Za-z0-9_-]{12})\.r_([A-Za-z0-9_-]{10})$/;
+const documentAiRefPattern = /^(b_[A-Za-z0-9_-]{12})\.r_([A-Za-z0-9_-]{6})$/;
export class DocumentAiHtmlError extends Error {}
export class WidgetScriptSyntaxError extends DocumentAiHtmlError {}
@@ -108,7 +108,7 @@ export async function createDocumentAiRef(node: ProseMirrorNode) {
// second DOM pass per block per read, and the ref only has to change when
// the block's content does.
const content = JSON.stringify(withTiptapNodeAiRef(node, null).toJSON());
- const revision = (await sha256Base64UrlText(content)).slice(0, 10);
+ const revision = (await sha256Base64UrlText(content)).slice(0, 6);
return `${blockId}.r_${revision}`;
}
@@ -116,16 +116,6 @@ export function parseDocumentAiRef(ref: string) {
return documentAiRefPattern.exec(ref)?.[1] ?? null;
}
-export function readDocumentAiRefRevision(ref: string) {
- return documentAiRefPattern.exec(ref)?.[2] ?? null;
-}
-
-export function readDocumentAiRefs(html: string) {
- return Array.from(html.matchAll(/\sdata-ref="([^"]+)"/g), (match) => match[1]!).filter((ref) =>
- documentAiRefPattern.test(ref),
- );
-}
-
export function ensureTiptapDocumentBlockIds(document: TiptapDocumentJson): {
changed: boolean;
document: TiptapDocumentJson;
@@ -375,6 +365,9 @@ export function applyDocumentCitationLocations(
case "flashcard":
element.setAttribute("data-card-id", location.cardId);
break;
+ case "quiz-question":
+ element.setAttribute("data-question-id", location.questionId);
+ break;
}
}
diff --git a/src/features/workspaces/documents/document-ai-html.worker.test.ts b/src/features/workspaces/documents/document-ai-html.worker.test.ts
index 2741508f..2b755a80 100644
--- a/src/features/workspaces/documents/document-ai-html.worker.test.ts
+++ b/src/features/workspaces/documents/document-ai-html.worker.test.ts
@@ -13,7 +13,7 @@ describe("document AI HTML in Workers", () => {
).document;
expect(await serializeTiptapDocumentToAiHtml(document)).toMatch(
- /^Worker<\/h2>
Schema-safe HTML<\/p>$/,
+ /^
Worker<\/h2>
Schema-safe HTML<\/p>$/,
);
});
});
diff --git a/src/features/workspaces/documents/document-html-chunk.ts b/src/features/workspaces/documents/document-html-chunk.ts
index 0810bda1..9d1991ce 100644
--- a/src/features/workspaces/documents/document-html-chunk.ts
+++ b/src/features/workspaces/documents/document-html-chunk.ts
@@ -17,18 +17,19 @@ export interface DocumentHtmlChunk {
}
export interface DocumentHtmlChunkReadInput {
- expectedRevision?: string;
offset: number;
+ /** Stop after this many blocks even if the character budget has room. */
+ maxBlocks?: number;
}
export type DocumentHtmlChunkReadResult =
- | { status: "content_changed" }
| { status: "invalid_offset" }
- | ({ revision: string; status: "ready" } & DocumentHtmlChunk);
+ | ({ status: "ready" } & DocumentHtmlChunk);
export async function readDocumentHtmlChunk(
document: ProseMirrorNode,
offset: number,
+ maxBlocks?: number,
): Promise {
if (offset < 0 || offset >= document.childCount) {
return undefined;
@@ -38,6 +39,7 @@ export async function readDocumentHtmlChunk(
let characters = 0;
let endOffset = offset;
while (endOffset < document.childCount) {
+ if (maxBlocks !== undefined && endOffset - offset >= maxBlocks) break;
const block = await serializeTiptapNodeToAiHtml(document.child(endOffset));
const separatorCharacters = content.length > 0 ? 1 : 0;
if (
diff --git a/src/features/workspaces/documents/document-session.ts b/src/features/workspaces/documents/document-session.ts
index 3b8c63c6..98049c23 100644
--- a/src/features/workspaces/documents/document-session.ts
+++ b/src/features/workspaces/documents/document-session.ts
@@ -51,7 +51,7 @@ import {
commitWorkspaceDocumentCheckpoint,
readWorkspaceDocumentCheckpoint,
} from "#/features/workspaces/persistence/workspace-document-checkpoints";
-import { sha256Base64Url, sha256Base64UrlText } from "#/lib/binary";
+import { sha256Base64UrlText } from "#/lib/binary";
const persistedYDocUpdateKey = "document-session:yjs-update";
const latestDocumentEditReceiptKey = "document-session:ai-edit-receipt:latest";
@@ -354,14 +354,10 @@ export class DocumentSession extends YServer {
async readHtmlChunk(input: DocumentHtmlChunkReadInput): Promise {
this.assertActive();
- const { document, stateVector } = await this.getReferencedDocumentSnapshot();
- const revision = await sha256Base64Url(stateVector);
- if (input.expectedRevision && input.expectedRevision !== revision) {
- return { status: "content_changed" };
- }
+ const { document } = await this.getReferencedDocumentSnapshot();
- const chunk = await readDocumentHtmlChunk(document, input.offset);
- return chunk ? { ...chunk, revision, status: "ready" } : { status: "invalid_offset" };
+ const chunk = await readDocumentHtmlChunk(document, input.offset, input.maxBlocks);
+ return chunk ? { ...chunk, status: "ready" } : { status: "invalid_offset" };
}
/**
diff --git a/src/features/workspaces/documents/tiptap-schema.ts b/src/features/workspaces/documents/tiptap-schema.ts
index fe794b81..fdf78a85 100644
--- a/src/features/workspaces/documents/tiptap-schema.ts
+++ b/src/features/workspaces/documents/tiptap-schema.ts
@@ -34,6 +34,7 @@ export const Citation = Node.create({
itemId: { default: null, parseHTML: (el) => el.getAttribute("data-item-id") },
blockId: { default: null, parseHTML: (el) => el.getAttribute("data-block-id") },
cardId: { default: null, parseHTML: (el) => el.getAttribute("data-card-id") },
+ questionId: { default: null, parseHTML: (el) => el.getAttribute("data-question-id") },
pageNumber: {
default: null,
parseHTML: (el) => {
@@ -55,6 +56,7 @@ export const Citation = Node.create({
"data-item-id": node.attrs.itemId,
...(node.attrs.blockId ? { "data-block-id": String(node.attrs.blockId) } : {}),
...(node.attrs.cardId ? { "data-card-id": String(node.attrs.cardId) } : {}),
+ ...(node.attrs.questionId ? { "data-question-id": String(node.attrs.questionId) } : {}),
...(node.attrs.pageNumber ? { "data-page": String(node.attrs.pageNumber) } : {}),
},
];
@@ -67,13 +69,15 @@ export function getWorkspaceCitationLocation(
const itemId = typeof attrs.itemId === "string" ? attrs.itemId : null;
if (!itemId) return undefined;
- const location = attrs.cardId
- ? { cardId: attrs.cardId, itemId, kind: "flashcard", version: 1 }
- : attrs.blockId
- ? { blockId: attrs.blockId, itemId, kind: "document-block", version: 1 }
- : attrs.pageNumber
- ? { itemId, kind: "pdf-page", pageNumber: attrs.pageNumber, version: 1 }
- : { itemId, kind: "item", version: 1 };
+ const location = attrs.questionId
+ ? { itemId, kind: "quiz-question", questionId: attrs.questionId, version: 1 }
+ : attrs.cardId
+ ? { cardId: attrs.cardId, itemId, kind: "flashcard", version: 1 }
+ : attrs.blockId
+ ? { blockId: attrs.blockId, itemId, kind: "document-block", version: 1 }
+ : attrs.pageNumber
+ ? { itemId, kind: "pdf-page", pageNumber: attrs.pageNumber, version: 1 }
+ : { itemId, kind: "item", version: 1 };
const parsed = workspaceLocationSchema.safeParse(location);
return parsed.success ? parsed.data : undefined;
diff --git a/src/features/workspaces/locations/workspace-location-context.test.tsx b/src/features/workspaces/locations/workspace-location-context.test.tsx
index f8dad677..6c80feeb 100644
--- a/src/features/workspaces/locations/workspace-location-context.test.tsx
+++ b/src/features/workspaces/locations/workspace-location-context.test.tsx
@@ -30,6 +30,7 @@ describe("WorkspaceLocationProvider", () => {
type: "file",
name: "Book.pdf",
color: null,
+ refKey: "ref-file-1",
metadataJson: {},
sortOrder: 1,
createdAt: "2026-08-13T00:00:00.000Z",
diff --git a/src/features/workspaces/locations/workspace-location-context.tsx b/src/features/workspaces/locations/workspace-location-context.tsx
index fceaae93..c59ea90f 100644
--- a/src/features/workspaces/locations/workspace-location-context.tsx
+++ b/src/features/workspaces/locations/workspace-location-context.tsx
@@ -2,7 +2,11 @@ import { FileQuestion, type LucideIcon } from "lucide-react";
import { createContext, type ReactNode, use, useCallback, useState } from "react";
import { toast } from "sonner";
-import type { WorkspaceLocation } from "#/features/workspaces/locations/workspace-location";
+import {
+ parseWorkspaceAddress,
+ resolveWorkspaceAddressLocation,
+ type WorkspaceLocation,
+} from "#/features/workspaces/locations/workspace-location";
import { getWorkspaceItemDisplay } from "#/features/workspaces/model/item-display";
import type { WorkspaceItem } from "#/features/workspaces/contracts";
@@ -24,6 +28,8 @@ type WorkspaceLocationContextValue = {
completeRevealRequest: (request: WorkspaceLocationRevealRequest, revealed: boolean) => void;
getItem: (itemId: string) => WorkspaceItem | undefined;
getPresentation: (location: WorkspaceLocation) => WorkspaceLocationPresentation;
+ /** Resolves a self-describing address like `Xk7p2Qa9/p5` against the live workspace. */
+ resolveAddress: (ref: unknown) => WorkspaceLocation | undefined;
reveal: (location: WorkspaceLocation) => boolean;
revealRequest: WorkspaceLocationRevealRequest | null;
};
@@ -56,6 +62,16 @@ export function WorkspaceLocationProvider({
getItem(itemId) {
return itemsById.get(itemId);
},
+ resolveAddress(ref) {
+ const address = typeof ref === "string" ? parseWorkspaceAddress(ref) : undefined;
+ if (!address) return undefined;
+ for (const item of itemsById.values()) {
+ if (item.refKey === address.refKey) {
+ return resolveWorkspaceAddressLocation(item, address);
+ }
+ }
+ return undefined;
+ },
getPresentation(location) {
const item = itemsById.get(location.itemId);
const itemName = item?.name ?? "Source unavailable";
@@ -95,6 +111,9 @@ function getWorkspaceLocatorLabel(location: WorkspaceLocation) {
return `p. ${location.pageNumber}`;
case "document-block":
case "flashcard":
+ case "quiz-question":
+ // Content-positional labels ("Card 3", "Question 3") need the item's
+ // current content, so the citation component supplies them.
return undefined;
}
}
diff --git a/src/features/workspaces/locations/workspace-location.test.ts b/src/features/workspaces/locations/workspace-location.test.ts
index 8ae8010d..85325813 100644
--- a/src/features/workspaces/locations/workspace-location.test.ts
+++ b/src/features/workspaces/locations/workspace-location.test.ts
@@ -1,108 +1,95 @@
import { describe, expect, it } from "vitest";
import {
- createWorkspaceReferenceRecords,
- getWorkspaceLocationKey,
- indexWorkspaceReferenceRecords,
- parseWorkspaceReference,
+ parseWorkspaceAddress,
+ parseWorkspaceUnitRef,
+ resolveWorkspaceAddressLocation,
workspaceLocationSchema,
} from "#/features/workspaces/locations/workspace-location";
-describe("workspace location", () => {
- it.each([
- [{ itemId: "item-1", kind: "item", version: 1 }, "1:item:item-1"],
- [{ itemId: "item-1", kind: "pdf-page", pageNumber: 12, version: 1 }, "1:pdf-page:item-1:12"],
- [
- {
- itemId: "item-1",
- kind: "flashcard",
- cardId: "f67080f9-0158-4565-86a9-4c90ed6809d2",
- version: 1,
- },
- "1:flashcard:item-1:f67080f9-0158-4565-86a9-4c90ed6809d2",
- ],
- [
- { blockId: "b_abcdefghijkl", itemId: "item-1", kind: "document-block", version: 1 },
- "1:document-block:item-1:b_abcdefghijkl",
- ],
- ])("parses and keys %o", (input, expectedKey) => {
- const result = workspaceLocationSchema.safeParse(input);
-
- expect(result.success).toBe(true);
- if (result.success) {
- expect(getWorkspaceLocationKey(result.data)).toBe(expectedKey);
- }
- });
-
- it.each([
- { itemId: "", kind: "item", version: 1 },
- { itemId: "item-1", kind: "pdf-page", pageNumber: 0, version: 1 },
- { cardId: "not-a-uuid", itemId: "item-1", kind: "flashcard", version: 1 },
- { blockId: "block-1", itemId: "item-1", kind: "document-block", version: 1 },
- { itemId: "item-1", kind: "item", version: 2 },
- { extra: true, itemId: "item-1", kind: "item", version: 1 },
- ])("rejects invalid location %o", (input) => {
- expect(workspaceLocationSchema.safeParse(input).success).toBe(false);
- });
-});
-
-describe("workspace reference", () => {
- it("creates an 11-character opaque reference", () => {
- const location = { itemId: "item-1", kind: "item", version: 1 } as const;
- const [{ ref }] = createWorkspaceReferenceRecords([location]);
-
- expect(ref).toMatch(/^wr_[0-9A-Za-z]{8}$/);
- expect(ref).toHaveLength(11);
- expect(parseWorkspaceReference(ref)).toBe(ref);
- });
-
- it("reuses one ref for the same durable location", () => {
- const location = { itemId: "item-1", kind: "pdf-page", pageNumber: 7, version: 1 } as const;
- const records = createWorkspaceReferenceRecords([location, { ...location }], {
- createCandidate: () => "wr_AAAAAAAA",
+describe("workspace addresses", () => {
+ it("parses item, unit, and revisioned forms", () => {
+ expect(parseWorkspaceAddress("Xk7p2Qa9")).toEqual({ refKey: "Xk7p2Qa9" });
+ expect(parseWorkspaceAddress("Xk7p2Qa9/p12")).toEqual({ refKey: "Xk7p2Qa9", unit: "p12" });
+ expect(parseWorkspaceAddress("Xk7p2Qa9/b_x7Kp2Qa9x8Lm.r_4f2a1b")).toEqual({
+ refKey: "Xk7p2Qa9",
+ unit: "b_x7Kp2Qa9x8Lm",
+ revision: "4f2a1b",
});
-
- expect(records).toEqual([{ location, ref: "wr_AAAAAAAA" }]);
- });
-
- it("retries a colliding candidate", () => {
- const candidates = ["wr_AAAAAAAA", "wr_AAAAAAAA", "wr_BBBBBBBB"];
- const records = createWorkspaceReferenceRecords(
- [
- { itemId: "item-1", kind: "item", version: 1 },
- { itemId: "item-2", kind: "item", version: 1 },
- ],
- {
- createCandidate: () => candidates.shift() ?? "wr_CCCCCCCC",
- },
- );
-
- expect(records.map(({ ref }) => ref)).toEqual(["wr_AAAAAAAA", "wr_BBBBBBBB"]);
+ expect(parseWorkspaceAddress("not an address")).toBeUndefined();
+ expect(parseWorkspaceAddress("wr_7Kp2Qa9x")).toBeUndefined();
});
- it("retains editable revisions and makes conflicting transcript refs unusable", () => {
- const location = {
- blockId: "b_abcdefghijkl",
+ it("interprets units against the item's type", () => {
+ const address = parseWorkspaceAddress("Xk7p2Qa9/p12")!;
+ expect(resolveWorkspaceAddressLocation({ id: "item-1", type: "file" }, address)).toEqual({
itemId: "item-1",
- kind: "document-block",
+ kind: "pdf-page",
+ pageNumber: 12,
version: 1,
- } as const;
- const [record] = createWorkspaceReferenceRecords([{ location, revision: "0123456789" }], {
- createCandidate: () => "wr_AAAAAAAA",
});
+ // The same unit means nothing on a document.
+ expect(
+ resolveWorkspaceAddressLocation({ id: "item-1", type: "document" }, address),
+ ).toBeUndefined();
- expect(record).toEqual({ location, ref: "wr_AAAAAAAA", revision: "0123456789" });
expect(
- indexWorkspaceReferenceRecords([record!, { ...record!, revision: "9876543210" }]).get(
- record!.ref,
+ resolveWorkspaceAddressLocation(
+ { id: "item-1", type: "flashcard" },
+ parseWorkspaceAddress("Xk7p2Qa9/c_9xKp2Qab")!,
+ ),
+ ).toEqual({ cardId: "c_9xKp2Qab", itemId: "item-1", kind: "flashcard", version: 1 });
+ expect(
+ resolveWorkspaceAddressLocation(
+ { id: "item-1", type: "quiz" },
+ parseWorkspaceAddress("Xk7p2Qa9/f67080f9-0158-4565-86a9-4c90ed6809d2")!,
+ ),
+ ).toEqual({
+ itemId: "item-1",
+ kind: "quiz-question",
+ questionId: "f67080f9-0158-4565-86a9-4c90ed6809d2",
+ version: 1,
+ });
+ expect(
+ resolveWorkspaceAddressLocation(
+ { id: "item-1", type: "document" },
+ parseWorkspaceAddress("Xk7p2Qa9")!,
),
- ).toBeNull();
+ ).toEqual({ itemId: "item-1", kind: "item", version: 1 });
});
- it.each(["", "wr_short", "xx_AAAAAAAA", "wr_!!!!!!!!", "wr_AAAAAAAAA"])(
- "rejects malformed ref %s",
- (input) => {
- expect(parseWorkspaceReference(input)).toBeUndefined();
- },
- );
+ it("parses edit unit refs with their revision", () => {
+ expect(parseWorkspaceUnitRef("b_x7Kp2Qa9x8Lm.r_4f2a1b")).toEqual({
+ unit: "b_x7Kp2Qa9x8Lm",
+ revision: "4f2a1b",
+ });
+ expect(parseWorkspaceUnitRef("b_x7Kp2Qa9x8Lm")).toBeUndefined();
+ });
+
+ it("keeps persisted locations validating legacy and short entry ids", () => {
+ expect(
+ workspaceLocationSchema.safeParse({
+ cardId: "f67080f9-0158-4565-86a9-4c90ed6809d2",
+ itemId: "item-1",
+ kind: "flashcard",
+ version: 1,
+ }).success,
+ ).toBe(true);
+ expect(
+ workspaceLocationSchema.safeParse({
+ cardId: "c_9xKp2Qab",
+ itemId: "item-1",
+ kind: "flashcard",
+ version: 1,
+ }).success,
+ ).toBe(true);
+ expect(
+ workspaceLocationSchema.safeParse({
+ cardId: "not-an-id",
+ itemId: "item-1",
+ kind: "flashcard",
+ version: 1,
+ }).success,
+ ).toBe(false);
+ });
});
diff --git a/src/features/workspaces/locations/workspace-location.ts b/src/features/workspaces/locations/workspace-location.ts
index 67f9dc81..89f94fdc 100644
--- a/src/features/workspaces/locations/workspace-location.ts
+++ b/src/features/workspaces/locations/workspace-location.ts
@@ -3,19 +3,30 @@ import { z } from "zod";
const WORKSPACE_REFERENCE_ALPHABET =
"0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
-const WORKSPACE_REFERENCE_RANDOM_LENGTH = 8;
-const WORKSPACE_REFERENCE_COLLISION_ATTEMPTS = 32;
-const createRandomWorkspaceReferenceSuffix = customAlphabet(
- WORKSPACE_REFERENCE_ALPHABET,
- WORKSPACE_REFERENCE_RANDOM_LENGTH,
-);
+/** Mints the short, durable, model-facing handle a workspace item keeps for life. */
+export const createWorkspaceItemRefKey = customAlphabet(WORKSPACE_REFERENCE_ALPHABET, 8);
const workspaceLocationItemIdSchema = z.string().trim().min(1);
+const createWorkspaceEntryIdSuffix = customAlphabet(WORKSPACE_REFERENCE_ALPHABET, 8);
+
+/** Mints the id of one card or question, e.g. `c_9xKp2Qab`. */
+export function createWorkspaceEntryId(prefix: "c" | "q") {
+ return `${prefix}_${createWorkspaceEntryIdSuffix()}`;
+}
+
/**
- * Durable, versioned pointer to content inside a workspace.
- *
- * Short AI-facing references are aliases for this value and must never replace
- * it in persisted application state.
+ * One flashcard or quiz-question id. Early content minted UUIDs; everything
+ * since mints the short prefixed form, and both stay valid ids forever.
+ */
+export const workspaceEntryIdSchema = z.union([
+ z.string().regex(/^[cq]_[0-9A-Za-z]{8}$/),
+ z.uuid(),
+]);
+
+/**
+ * Durable, versioned pointer to content inside a workspace, as persisted by
+ * document and chat citations. Model-facing addresses parse into this against
+ * the item they name.
*/
export const workspaceLocationSchema = z.discriminatedUnion("kind", [
z.strictObject({
@@ -38,7 +49,13 @@ export const workspaceLocationSchema = z.discriminatedUnion("kind", [
z.strictObject({
itemId: workspaceLocationItemIdSchema,
kind: z.literal("flashcard"),
- cardId: z.uuid(),
+ cardId: workspaceEntryIdSchema,
+ version: z.literal(1),
+ }),
+ z.strictObject({
+ itemId: workspaceLocationItemIdSchema,
+ kind: z.literal("quiz-question"),
+ questionId: workspaceEntryIdSchema,
version: z.literal(1),
}),
]);
@@ -46,127 +63,89 @@ export const workspaceLocationSchema = z.discriminatedUnion("kind", [
/** A parsed durable workspace location. */
export type WorkspaceLocation = Readonly>;
-/** Schema for the exact short reference the model is allowed to copy. */
-export const workspaceReferenceInputSchema = z.string().regex(/^wr_[0-9A-Za-z]{8}$/);
-export const workspaceReferenceSchema = workspaceReferenceInputSchema.brand<"WorkspaceReference">();
-
-/** Short model-facing alias for a durable workspace location. */
-export type WorkspaceReference = z.output;
-
-/** Schema for a durable location retained behind a short reference. */
-export const workspaceReferenceRecordSchema = z.strictObject({
- location: workspaceLocationSchema,
- ref: workspaceReferenceSchema,
- revision: z
- .string()
- .regex(/^[A-Za-z0-9_-]{10}$/)
- .optional(),
-});
-
-/** Durable record retained behind a short workspace reference. */
-export type WorkspaceReferenceRecord = Readonly>;
-
/**
- * Produces the canonical in-memory key for a workspace location.
+ * The model-facing address grammar: `refKey[/unit][.r_revision]`.
*
- * @param location - Parsed workspace location.
- * @returns A collision-free key within location schema version 1.
+ * `refKey` is the item's durable 8-character handle. `unit` names one piece of
+ * it — `p5` a physical page, `b_…` a document block, a card or question id for
+ * study items — and is interpreted against the item's type, so the token never
+ * has to encode what kind of thing it names. `.r_…` carries the 6-character
+ * content revision an edit must present. The whole string is self-describing:
+ * nothing has to be minted, stored, or kept alive server-side for it to
+ * resolve, so an address from any point in a conversation keeps working.
*/
-export function getWorkspaceLocationKey(location: WorkspaceLocation) {
- switch (location.kind) {
- case "item":
- return `1:item:${location.itemId}`;
- case "pdf-page":
- return `1:pdf-page:${location.itemId}:${location.pageNumber}`;
- case "document-block":
- return `1:document-block:${location.itemId}:${location.blockId}`;
- case "flashcard":
- return `1:flashcard:${location.itemId}:${location.cardId}`;
- }
-}
+const workspaceAddressPattern =
+ /^([0-9A-Za-z]{8})(?:\/([A-Za-z0-9_-]{1,40}?))?(?:\.r_([A-Za-z0-9_-]{6}))?$/;
-/**
- * Parses an untrusted short workspace reference.
- *
- * @param input - Untrusted model or persisted value.
- * @returns A branded reference when valid.
- */
-export function parseWorkspaceReference(input: unknown) {
- const parsed = workspaceReferenceSchema.safeParse(input);
+export const workspaceAddressInputSchema = z.string().regex(workspaceAddressPattern);
- return parsed.success ? parsed.data : undefined;
+export interface WorkspaceAddress {
+ refKey: string;
+ unit?: string;
+ revision?: string;
}
-/** Index app-issued refs while making collisions unusable. */
-export function indexWorkspaceReferenceRecords(
- records: readonly WorkspaceReferenceRecord[],
-): ReadonlyMap {
- const index = new Map();
- for (const record of records) {
- const existing = index.get(record.ref);
- if (existing === undefined) {
- index.set(record.ref, record);
- } else if (
- existing &&
- (getWorkspaceLocationKey(existing.location) !== getWorkspaceLocationKey(record.location) ||
- existing.revision !== record.revision)
- ) {
- index.set(record.ref, null);
- }
- }
- return index;
+export function parseWorkspaceAddress(input: unknown): WorkspaceAddress | undefined {
+ if (typeof input !== "string") return undefined;
+ const match = workspaceAddressPattern.exec(input.trim());
+ if (!match) return undefined;
+ return {
+ refKey: match[1]!,
+ ...(match[2] ? { unit: match[2] } : {}),
+ ...(match[3] ? { revision: match[3] } : {}),
+ };
}
/**
- * Creates deduplicated, collision-checked refs for durable locations.
- *
- * The optional candidate source is an internal test seam. Production callers
- * should use the default cryptographically strong Nano ID source.
+ * Interprets an address's unit against the item it names.
*
- * @param locations - Durable locations in desired record order.
- * @param options - Optional candidate source for deterministic verification.
- * @returns One reference record per distinct location.
+ * @returns The durable location, or undefined when the unit cannot belong to
+ * an item of this type.
*/
-export function createWorkspaceReferenceRecords(
- targets: readonly (WorkspaceLocation | { location: WorkspaceLocation; revision: string })[],
- options: { readonly createCandidate?: () => string } = {},
-): WorkspaceReferenceRecord[] {
- const createCandidate =
- options.createCandidate ?? (() => `wr_${createRandomWorkspaceReferenceSuffix()}`);
- const locationKeys = new Set();
- const refs = new Set();
- const records: WorkspaceReferenceRecord[] = [];
-
- for (const target of targets) {
- const { location, revision } =
- "location" in target ? target : { location: target, revision: undefined };
- const locationKey = getWorkspaceLocationKey(location);
- if (locationKeys.has(locationKey)) {
- continue;
- }
-
- let allocatedRef: WorkspaceReference | undefined;
- for (let attempt = 0; attempt < WORKSPACE_REFERENCE_COLLISION_ATTEMPTS; attempt += 1) {
- const ref = parseWorkspaceReference(createCandidate());
- if (!ref) {
- throw new Error("Workspace reference candidate source returned an invalid value.");
- }
- if (refs.has(ref)) {
- continue;
- }
-
- allocatedRef = ref;
- break;
- }
+export function resolveWorkspaceAddressLocation(
+ item: { id: string; type: "document" | "file" | "flashcard" | "folder" | "quiz" },
+ address: WorkspaceAddress,
+): WorkspaceLocation | undefined {
+ if (address.unit === undefined) {
+ return { itemId: item.id, kind: "item", version: 1 };
+ }
+ if (item.type === "file") {
+ const page = /^p([1-9]\d{0,5})$/.exec(address.unit);
+ return page
+ ? { itemId: item.id, kind: "pdf-page", pageNumber: Number(page[1]), version: 1 }
+ : undefined;
+ }
+ if (item.type === "document") {
+ return /^b_[A-Za-z0-9_-]{12}$/.test(address.unit)
+ ? { blockId: address.unit, itemId: item.id, kind: "document-block", version: 1 }
+ : undefined;
+ }
+ if (item.type === "flashcard") {
+ const cardId = workspaceEntryIdSchema.safeParse(address.unit);
+ return cardId.success
+ ? { cardId: cardId.data, itemId: item.id, kind: "flashcard", version: 1 }
+ : undefined;
+ }
+ if (item.type === "quiz") {
+ const questionId = workspaceEntryIdSchema.safeParse(address.unit);
+ return questionId.success
+ ? { itemId: item.id, kind: "quiz-question", questionId: questionId.data, version: 1 }
+ : undefined;
+ }
+ return undefined;
+}
- if (!allocatedRef) {
- throw new Error("Unable to allocate a collision-free workspace reference.");
- }
+/**
+ * A unit ref as copied from a read into an edit: `unit.r_revision`. The item
+ * is already named by the edit call's path, so the ref stays item-relative.
+ */
+const workspaceUnitRefPattern = /^([A-Za-z0-9_-]{1,40}?)\.r_([A-Za-z0-9_-]{6})$/;
- locationKeys.add(locationKey);
- refs.add(allocatedRef);
- records.push({ location, ref: allocatedRef, ...(revision ? { revision } : {}) });
- }
+export const workspaceUnitRefInputSchema = z.string().regex(workspaceUnitRefPattern);
- return records;
+export function parseWorkspaceUnitRef(
+ input: string,
+): { unit: string; revision: string } | undefined {
+ const match = workspaceUnitRefPattern.exec(input);
+ return match ? { unit: match[1]!, revision: match[2]! } : undefined;
}
diff --git a/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap b/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap
index ef7c7572..5f94c410 100644
--- a/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap
+++ b/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap
@@ -105,7 +105,7 @@ exports[`workspace tool surface > workspace_create_items input schema is stable
"description": "Document to create.",
"properties": {
"initialContent": {
- "description": "Optional initial HTML content. Use semantic HTML with paragraphs, h1-h4, blockquotes, lists, code blocks, horizontal rules, tables, links, and standard text marks. This is HTML, so math is markup rather than delimiters: use or , and keep dollar signs out of the data-latex value. Put every subscript and superscript (exponents like 10^8, indices like x_1) inside math rather than / tags. Chemistry renders with \\ce{...} (e.g. \\ce{CH4 + 2 O2 -> CO2 + 2 H2O}) and quantities with units render with \\pu{...} (e.g. \\pu{9.81 m/s^2}), both inside data-latex. Write literal money as plain text ($30, never \\$30) — a backslash before a dollar sign shows on screen in HTML. For checkboxes, use Item
. Documents cannot hold images: never use ![]()
or , and describe the visual in words instead. Cite workspace sources in documents exactly as in a chat reply, with Item
. Documents cannot hold images: never use ![]()
or , and describe the visual in words instead. Cite workspace sources in documents exactly as in a chat reply, with Item
. Documents cannot hold images: never use ![]()
or , and describe the visual in words instead. Cite workspace sources in documents exactly as in a chat reply, with Item
. Documents cannot hold images: never use ![]()
or , and describe the visual in words instead. Cite workspace sources in documents exactly as in a chat reply, with {
const refs = readDocumentCitationRefs(input.html);
- if (refs.length === 0 || !input.context.resolveWorkspaceReferences) {
+ if (refs.length === 0) {
return input.html;
}
- const records = await input.context.resolveWorkspaceReferences(refs);
- const locations = new Map(
- [...indexWorkspaceReferenceRecords(records)].flatMap(([ref, record]) =>
- record ? [[ref, record.location] as const] : [],
- ),
- );
+ const locations = new Map();
+ for (const ref of new Set(refs)) {
+ const address = parseWorkspaceAddress(ref);
+ if (!address) continue;
+ const resolved = await getWorkspaceItemByRefKey({
+ refKey: address.refKey,
+ workspaceId: input.context.workspaceId,
+ });
+ const location = resolved ? resolveWorkspaceAddressLocation(resolved.item, address) : undefined;
+ if (location) locations.set(ref, location);
+ }
return applyDocumentCitationLocations(input.html, locations);
}
diff --git a/src/features/workspaces/operations/edit-item.ts b/src/features/workspaces/operations/edit-item.ts
index 30cde027..d9e65039 100644
--- a/src/features/workspaces/operations/edit-item.ts
+++ b/src/features/workspaces/operations/edit-item.ts
@@ -12,20 +12,22 @@ import { resolveDocumentCitations } from "#/features/workspaces/operations/docum
import {
applyFlashcardEdits,
type FlashcardEdit,
- type FlashcardEditTarget,
} from "#/features/workspaces/flashcards/flashcard-edits";
import { updateFlashcardSet } from "#/features/workspaces/flashcards/flashcard-persistence";
+import { applyQuizEdits, type QuizEdit } from "#/features/workspaces/quizzes/quiz-edits";
+import { updateQuizSet } from "#/features/workspaces/quizzes/quiz-persistence";
+import type { OrderedEntryEditTarget } from "#/features/workspaces/content/ordered-entry-edits";
import {
- indexWorkspaceReferenceRecords,
- parseWorkspaceReference,
- type WorkspaceReferenceRecord,
+ parseWorkspaceUnitRef,
+ workspaceEntryIdSchema,
} from "#/features/workspaces/locations/workspace-location";
type EditWorkspaceItemFailureCode = (typeof editWorkspaceItemFailureCodes)[number];
export type EditWorkspaceItemOperationInput =
| { edits: DocumentAiEdit[]; path: string; type: "document" }
- | { edits: FlashcardEdit[]; path: string; type: "flashcard" };
+ | { edits: FlashcardEdit[]; path: string; type: "flashcard" }
+ | { edits: QuizEdit[]; path: string; type: "quiz" };
interface EditWorkspaceItemFailure {
code: EditWorkspaceItemFailureCode;
@@ -37,7 +39,7 @@ export interface EditWorkspaceItemOperationResult {
applied: number;
failed: EditWorkspaceItemFailure[];
itemId?: string;
- itemType?: "document" | "flashcard";
+ itemType?: "document" | "flashcard" | "quiz";
lineChanges?: DocumentEditLineChanges;
path: string;
}
@@ -77,66 +79,51 @@ export async function editWorkspaceItemOperation(
};
}
- if (input.type === "flashcard") {
- const targets = await resolveEditTargets(
- accessContext,
- input.edits,
- (record) =>
- record.location.kind === "flashcard" &&
- record.location.itemId === resolution.item.id &&
- record.revision
- ? { cardId: record.location.cardId, revision: record.revision }
- : undefined,
- );
+ if (input.type === "flashcard" || input.type === "quiz") {
+ const itemId = resolution.item.id;
+ const targets = collectEntryEditTargets(input.edits);
const { env } = await import("cloudflare:workers");
- const result = await updateFlashcardSet(
- env,
- {
- actorUserId: accessContext.actor.userId,
- itemId: resolution.item.id,
- workspaceId: accessContext.workspaceId,
- },
- async (content) => {
- const applied = await applyFlashcardEdits(content, input.edits, targets);
- return { changed: applied.applied > 0, content: applied.content, result: applied };
- },
- );
+ const persistenceInput = {
+ actorUserId: accessContext.actor.userId,
+ itemId,
+ workspaceId: accessContext.workspaceId,
+ };
+ const result =
+ input.type === "flashcard"
+ ? await updateFlashcardSet(env, persistenceInput, async (content) => {
+ const applied = await applyFlashcardEdits(content, input.edits, targets);
+ return { changed: applied.applied > 0, content: applied.content, result: applied };
+ })
+ : await updateQuizSet(env, persistenceInput, async (content) => {
+ const applied = await applyQuizEdits(content, input.edits, targets);
+ return { changed: applied.applied > 0, content: applied.content, result: applied };
+ });
return {
applied: result.applied,
failed: result.failed,
- itemId: resolution.item.id,
- itemType: "flashcard",
+ itemId,
+ itemType: input.type,
path: resolution.path,
};
}
- const [targets, documentSession] = await Promise.all([
- resolveEditTargets(accessContext, input.edits, (record) =>
- record.location.kind === "document-block" &&
- record.location.itemId === resolution.item.id &&
- record.revision
- ? `${record.location.blockId}.r_${record.revision}`
- : undefined,
- ),
- getDocumentSession({
- itemId: resolution.item.id,
- workspaceId: accessContext.workspaceId,
- }),
- ]);
+ const documentSession = await getDocumentSession({
+ itemId: resolution.item.id,
+ workspaceId: accessContext.workspaceId,
+ });
const result = await documentSession.applyEdits({
edits: await Promise.all(
- input.edits.map(async (edit) => {
- const contentEdit = replacePublicRefs(edit, targets);
- return "html" in contentEdit
+ input.edits.map(async (edit) =>
+ "html" in edit
? {
- ...contentEdit,
+ ...edit,
html: await resolveDocumentCitations({
context: accessContext,
- html: contentEdit.html,
+ html: edit.html,
}),
}
- : contentEdit;
- }),
+ : edit,
+ ),
),
operationId: accessContext.operationId,
});
@@ -151,52 +138,27 @@ export async function editWorkspaceItemOperation(
};
}
-async function resolveEditTargets<
- TEdit extends { ref: string; afterRef?: string; beforeRef?: string },
- TTarget,
->(
- context: WorkspaceAccessContext,
- edits: readonly TEdit[],
- toTarget: (record: WorkspaceReferenceRecord) => TTarget | undefined,
+/**
+ * Parses every entry ref an edit batch mentions. A unit ref is self-contained
+ * — entry id plus content revision — so targeting needs no lookup; a ref whose
+ * unit is not an entry id simply resolves to nothing and the edit engine
+ * reports `ref_not_found` at the right index.
+ */
+function collectEntryEditTargets(
+ edits: readonly { ref: string; afterRef?: string; beforeRef?: string }[],
) {
- const refs = [...new Set(edits.flatMap(getReferencedRefs))];
- const records =
- refs.length > 0 && context.resolveWorkspaceReferences
- ? await context.resolveWorkspaceReferences(refs)
- : [];
- const recordsByRef = indexWorkspaceReferenceRecords(records);
- const targets = new Map();
- for (const ref of refs) {
- const parsedRef = parseWorkspaceReference(ref);
- const record = parsedRef ? recordsByRef.get(parsedRef) : undefined;
- const target = record ? toTarget(record) : undefined;
- if (target) targets.set(ref, target);
+ const targets = new Map();
+ for (const edit of edits) {
+ for (const ref of [edit.ref, edit.beforeRef, edit.afterRef]) {
+ if (!ref || targets.has(ref)) continue;
+ const parsed = parseWorkspaceUnitRef(ref);
+ if (!parsed || !workspaceEntryIdSchema.safeParse(parsed.unit).success) continue;
+ targets.set(ref, { entryId: parsed.unit, revision: parsed.revision });
+ }
}
-
return targets;
}
-function replacePublicRefs(
- edit: TEdit,
- targets: ReadonlyMap,
-): TEdit {
- // Unresolved refs stay invalid so the document engine reports them at their original edit index.
- return {
- ...edit,
- ref: targets.get(edit.ref) ?? edit.ref,
- ...(edit.beforeRef ? { beforeRef: targets.get(edit.beforeRef) ?? edit.beforeRef } : {}),
- ...(edit.afterRef ? { afterRef: targets.get(edit.afterRef) ?? edit.afterRef } : {}),
- };
-}
-
-function getReferencedRefs(edit: { ref: string; afterRef?: string; beforeRef?: string }) {
- return [
- edit.ref,
- ...(edit.beforeRef ? [edit.beforeRef] : []),
- ...(edit.afterRef ? [edit.afterRef] : []),
- ];
-}
-
async function getDocumentSession(input: { itemId: string; workspaceId: string }) {
const { env } = await import("cloudflare:workers");
diff --git a/src/features/workspaces/operations/read-items.ts b/src/features/workspaces/operations/read-items.ts
index fafde068..8f4ba239 100644
--- a/src/features/workspaces/operations/read-items.ts
+++ b/src/features/workspaces/operations/read-items.ts
@@ -6,13 +6,10 @@ import {
} from "#/features/workspaces/content/workspace-content-contract";
import { readWorkspaceContent } from "#/features/workspaces/content/workspace-content-reader";
import { recordWorkspaceFileReadOutcomes } from "#/features/workspaces/content/workspace-read-observability";
-import { createWorkspaceReadReferences } from "#/features/workspaces/content/workspace-read-references";
import { getDocumentSessionFromEnv } from "#/features/workspaces/document-session-access";
import { readFlashcardViewer } from "#/features/workspaces/flashcards/flashcard-study-persistence";
-import {
- indexWorkspaceReferenceRecords,
- parseWorkspaceReference,
-} from "#/features/workspaces/locations/workspace-location";
+import { readQuizViewer } from "#/features/workspaces/quizzes/quiz-study-persistence";
+import { getWorkspaceItemByRefKey } from "#/features/workspaces/persistence/workspace-items";
import type { WorkspaceAccessContext } from "#/features/workspaces/operations/workspace-access-context";
import { authorizeWorkspaceOperation } from "#/features/workspaces/operations/workspace-operation-context";
@@ -28,14 +25,6 @@ export async function readWorkspaceItemsOperation(
access: "read",
context: accessContext,
});
- const requestedRefs = input.requests.flatMap((request) =>
- request.mode === "ref" ? [request.ref] : [],
- );
- const referenceTargets = indexWorkspaceReferenceRecords(
- requestedRefs.length > 0 && accessContext.resolveWorkspaceReferences
- ? await accessContext.resolveWorkspaceReferences(requestedRefs)
- : [],
- );
const results = await readWorkspaceContent({
bucket: env.WORKSPACE_FILES,
getDocumentSession: (itemId) =>
@@ -49,11 +38,14 @@ export async function readWorkspaceItemsOperation(
userId: accessContext.actor.userId,
workspaceId: accessContext.workspaceId,
}),
- resolveReference: (itemId, ref) => {
- const parsedRef = parseWorkspaceReference(ref);
- const record = parsedRef ? referenceTargets.get(parsedRef) : undefined;
- return record?.location.itemId === itemId ? record.location : undefined;
- },
+ readQuizItem: (itemId) =>
+ readQuizViewer({
+ itemId,
+ userId: accessContext.actor.userId,
+ workspaceId: accessContext.workspaceId,
+ }),
+ resolveRefKey: (refKey) =>
+ getWorkspaceItemByRefKey({ refKey, workspaceId: accessContext.workspaceId }),
requests: input.requests,
workspaceId: accessContext.workspaceId,
});
@@ -65,8 +57,5 @@ export async function readWorkspaceItemsOperation(
workspaceId: accessContext.workspaceId,
});
- return {
- references: createWorkspaceReadReferences(results),
- results,
- };
+ return { results };
}
diff --git a/src/features/workspaces/operations/workspace-access-context.ts b/src/features/workspaces/operations/workspace-access-context.ts
index 0078c27a..ad3970f3 100644
--- a/src/features/workspaces/operations/workspace-access-context.ts
+++ b/src/features/workspaces/operations/workspace-access-context.ts
@@ -1,4 +1,3 @@
-import type { WorkspaceReferenceRecord } from "#/features/workspaces/locations/workspace-location";
import {
assertAccessScope,
createAccessActor,
@@ -11,27 +10,18 @@ export type WorkspaceAccessScope = (typeof workspaceAccessScopes)[number];
export interface WorkspaceAccessContext extends ScopedAccessContext {
operationId: string;
- /**
- * Resolves short refs retained in the chat transcript for reads, edits,
- * citations, and navigation. Absent outside a chat turn.
- */
- resolveWorkspaceReferences?: (refs: readonly string[]) => Promise;
workspaceId: string;
}
export function createWorkspaceAccessContext(input: {
scopes: readonly WorkspaceAccessScope[];
operationId: string;
- resolveWorkspaceReferences?: (refs: readonly string[]) => Promise;
userId: string;
workspaceId: string;
}): WorkspaceAccessContext {
return {
actor: createAccessActor(input),
operationId: input.operationId,
- ...(input.resolveWorkspaceReferences
- ? { resolveWorkspaceReferences: input.resolveWorkspaceReferences }
- : {}),
workspaceId: input.workspaceId,
};
}
diff --git a/src/features/workspaces/operations/workspace-tool-definitions.ts b/src/features/workspaces/operations/workspace-tool-definitions.ts
index 79c951f5..8f4bf8f1 100644
--- a/src/features/workspaces/operations/workspace-tool-definitions.ts
+++ b/src/features/workspaces/operations/workspace-tool-definitions.ts
@@ -144,7 +144,7 @@ export const workspaceToolDefinitions = [
name: "workspace_read_items",
access: "read",
description:
- "Read ThinkEx documents, flashcard sets, and extracted files by absolute path. Document chunks and flashcards include short, freshness-checked refs. Flashcard reads also return HTML fronts and backs plus the current user's study progress; again means missed, while hard, good, and easy mean got it. Use mode cards with a card-number range for targeted flashcard reads. Continue long documents, flashcard sets, or files with nextCursor. Use mode ref to read the exact content identified by an earlier ref; this returns elided widget source in full before editing. Files also support physical-page selections.",
+ "Read ThinkEx documents, flashcard sets, quizzes, and extracted files. Every item is an ordered list of units — document blocks, cards, questions, or physical pages — and every result names the numbered units it covered plus the total, so continue by requesting the next range: mode entries for blocks, cards, or questions; mode pages for file pages. mode start returns the first chunk. Each result carries the item's durable ref, and blocks, cards, and questions carry unit refs with a current .r_ revision — copy them exactly into edits, and cite as ref or ref/unit. Use mode ref with an address to read one unit in full; that is how elided widget source is fetched before editing. Flashcard reads include the current user's study progress (again means missed; hard, good, and easy mean got it). Quiz reads return options in user-visible order with the correct one marked, plus the user's answers and score.",
inputSchema: workspaceReadItemsInputSchema,
inputExamples: workspaceReadItemsInputExamples,
outputSchema: workspaceReadItemsOutputSchema,
@@ -192,7 +192,7 @@ export const workspaceToolDefinitions = [
name: "workspace_create_items",
access: "write",
description:
- "Create folders, documents, or flashcard sets at exact absolute paths. A slash separates folders, so use another character inside an item name. Set type and provide that branch's fields. If a path already exists, creation fails instead of renaming.",
+ "Create folders, documents, flashcard sets, or quizzes at exact absolute paths. A slash separates folders, so use another character inside an item name. Set type and provide that branch's fields. If a path already exists, creation fails instead of renaming.",
inputSchema: workspaceCreateItemsInputSchema,
inputExamples: workspaceCreateItemsInputExamples,
outputSchema: workspaceCreateItemsOutputSchema,
@@ -223,7 +223,7 @@ export const workspaceToolDefinitions = [
name: "workspace_edit_item",
access: "write",
description:
- "Edit one document or flashcard set by absolute path. Read it first, then copy the exact refs it returned. The same refs also work for citations and navigation. Flashcard edits apply immediately; document edits retain their review flow. Use workspace_link_items for item-level relationships.",
+ "Edit one document, flashcard set, or quiz by absolute path. Read it first, then copy each target's exact unit ref (like b_x7Kp2Qa9x8Lm.r_4f2a1b) from that read; the .r_ revision is how a stale edit fails loudly instead of hitting the wrong content. Flashcard and quiz edits apply immediately; document edits retain their review flow. Use workspace_link_items for item-level relationships.",
inputSchema: workspaceEditItemInputSchema,
inputExamples: workspaceEditItemInputExamples,
outputSchema: workspaceEditItemOutputSchema,
diff --git a/src/features/workspaces/operations/workspace-tool-schemas.ts b/src/features/workspaces/operations/workspace-tool-schemas.ts
index 92d2587f..c6f02e4b 100644
--- a/src/features/workspaces/operations/workspace-tool-schemas.ts
+++ b/src/features/workspaces/operations/workspace-tool-schemas.ts
@@ -17,7 +17,6 @@ import {
workspaceItemTypeSchema,
workspaceRelationKindSchema,
} from "#/features/workspaces/contracts";
-import { workspaceReferenceRecordSchema } from "#/features/workspaces/locations/workspace-location";
import {
documentAiEditSchema,
documentAiHtmlSchema,
@@ -25,6 +24,7 @@ import {
import { workspaceFileAssetKindSchema } from "#/features/workspaces/model/workspace-file";
import { flashcardEditSchema } from "#/features/workspaces/flashcards/flashcard-edits";
import { flashcardSideHtmlSchema } from "#/features/workspaces/flashcards/flashcard-content";
+import { quizEditSchema, quizQuestionInputSchema } from "#/features/workspaces/quizzes/quiz-edits";
export { workspaceReadItemsInputSchema, workspaceReadItemsOutputSchema };
@@ -42,10 +42,12 @@ const workspaceHtmlMathInstruction =
*/
const workspaceWidgetHtmlInstruction = `A widget is one interactive block inside a document. Use one when the user explicitly asks for a widget, asks for interaction or live computation, or wants a document visual that ordinary blocks cannot express. Keep ordinary content in ordinary blocks. Before authoring or editing widget source, activate the "widget-authoring" skill and follow its HTML, sandbox, layout, and editing contract. Serialize the result as …HTML-escaped fragment….`;
-export const workspaceDocumentHtmlInstruction = `Use semantic HTML with paragraphs, h1-h4, blockquotes, lists, code blocks, horizontal rules, tables, links, and standard text marks. ${workspaceHtmlMathInstruction} For checkboxes, use Item
. Documents cannot hold images: never use ![]()
or , and describe the visual in words instead. Cite workspace sources in documents exactly as in a chat reply, with Item
. Documents cannot hold images: never use ![]()
or , and describe the visual in words instead. Cite workspace sources in documents exactly as in a chat reply, with What is ATP?
", back: "The cell's main energy carrier.
" }],
},
+ {
+ type: "quiz",
+ path: "/Demo Folder/Demo Quiz",
+ questions: [
+ {
+ question: "What does ATP primarily provide to a cell?
",
+ correctAnswer: "Readily usable chemical energy
",
+ distractors: [
+ "Long-term energy storage
",
+ "Structural support for the membrane
",
+ "Genetic information for protein synthesis
",
+ ],
+ explanation:
+ "ATP transfers readily usable energy; fats store energy long-term, membranes get structure from lipids and proteins, and genetic information lives in DNA.
",
+ },
+ ],
+ },
],
});
@@ -354,7 +404,7 @@ export const workspaceEditItemInputExamples = createInputExamples<
path: "/Demo Folder/Demo Document",
edits: [
{
- ref: "wr_7Kp2Qa9x",
+ ref: "b_x7Kp2Qa9x8Lm.r_4f2a1b",
op: "replace",
html: "Updated paragraph.
",
},
@@ -365,8 +415,8 @@ export const workspaceEditItemInputExamples = createInputExamples<
path: "/Demo Folder/Demo Document",
edits: [
{
- ref: "wr_7Kp2Qa9x",
- afterRef: "wr_8Lq3Rb0y",
+ ref: "b_x7Kp2Qa9x8Lm.r_4f2a1b",
+ afterRef: "b_y8Lq3Rb0y9Mn.r_9c3d2e",
op: "move",
},
],
@@ -376,7 +426,7 @@ export const workspaceEditItemInputExamples = createInputExamples<
path: "/Demo Folder/Demo Document",
edits: [
{
- ref: "wr_7Kp2Qa9x",
+ ref: "b_x7Kp2Qa9x8Lm.r_4f2a1b",
op: "replace_text",
find: "gravity = 9.8",
replace: "gravity = 3.7",
@@ -389,11 +439,24 @@ export const workspaceEditItemInputExamples = createInputExamples<
edits: [
{
op: "update",
- ref: "wr_7Kp2Qa9x",
+ ref: "c_9xKp2Qab.r_4f2a1b",
back: "The cell's main energy carrier.
",
},
],
},
+ {
+ type: "quiz",
+ path: "/Demo Folder/Demo Quiz",
+ edits: [
+ {
+ op: "replace_text",
+ ref: "q_8Lq3Rb0y.r_9c3d2e",
+ field: "options",
+ find: "Long-term energy storage",
+ replace: "Long-term energy reserves",
+ },
+ ],
+ },
);
export const workspaceLinkItemsInputExamples = createInputExamples<
@@ -424,13 +487,12 @@ export const workspaceListItemsOutputSchema = z.object({
export const workspaceCreateItemsOutputSchema = createWorkspaceItemsResultSchema({
itemSchema: workspacePathItemSchema.extend({
itemId: z.string().min(1),
- type: z.enum(["document", "flashcard", "folder"]),
+ ref: z.string().min(1).describe("The item's durable address for citations and reads."),
+ type: z.enum(["document", "flashcard", "folder", "quiz"]),
}),
failureSchema: createFailureSchema(createWorkspaceItemsFailureCodes).extend({
detail: z.string().optional().describe("Why this item was refused, when the reason is known."),
}),
-}).extend({
- references: z.array(workspaceReferenceRecordSchema),
});
export const workspaceDeleteItemsOutputSchema = createWorkspaceItemsResultSchema({
@@ -456,7 +518,7 @@ export const workspaceEditItemOutputSchema = z.object({
path: workspacePathSchema,
applied: z.number().int().min(0),
itemId: z.string().optional(),
- itemType: z.enum(["document", "flashcard"]).optional(),
+ itemType: z.enum(["document", "flashcard", "quiz"]).optional(),
lineChanges: z
.object({ added: z.number().int().min(0), removed: z.number().int().min(0) })
.optional(),
diff --git a/src/features/workspaces/operations/workspace-tool-surface.test.ts b/src/features/workspaces/operations/workspace-tool-surface.test.ts
index 7ad877ab..e9bae42a 100644
--- a/src/features/workspaces/operations/workspace-tool-surface.test.ts
+++ b/src/features/workspaces/operations/workspace-tool-surface.test.ts
@@ -45,10 +45,10 @@ describe("workspace tool surface", () => {
}
it("gives documents and flashcards the same edit verbs and ref protocol", () => {
- const documentRef = "wr_AAAAAAAA";
- const otherDocumentRef = "wr_BBBBBBBB";
- const flashcardRef = "wr_CCCCCCCC";
- const otherFlashcardRef = "wr_DDDDDDDD";
+ const documentRef = "b_x7Kp2Qa9x8Lm.r_4f2a1b";
+ const otherDocumentRef = "b_y8Lq3Rb0y9Mn.r_9c3d2e";
+ const flashcardRef = "c_9xKp2Qab.r_4f2a1b";
+ const otherFlashcardRef = "c_8Lq3Rb0y.r_9c3d2e";
const sharedVerbs = [
"insert_before",
"insert_after",
diff --git a/src/lib/binary.ts b/src/lib/binary.ts
index f04ffe7b..aab904fe 100644
--- a/src/lib/binary.ts
+++ b/src/lib/binary.ts
@@ -21,10 +21,6 @@ export function decodeBase64Url(value: string) {
return Uint8Array.from(atob(padded), (character) => character.charCodeAt(0));
}
-export function encodeBase64UrlText(value: string) {
- return encodeBase64Url(textEncoder.encode(value));
-}
-
export function decodeBase64UrlText(value: string) {
return textDecoder.decode(decodeBase64Url(value));
}
From ffd73aa5481dd90fbecf81d357c68b6891a92c25 Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Sat, 15 Aug 2026 01:34:51 -0400
Subject: [PATCH 04/14] fix(workspaces): apply fresh-eyes review findings
Entry-range failures carry their real codes and a recovery message,
the range description no longer teaches comma lists to documents, and
the simplification pass lands: one shared Fisher-Yates, alias chains
and the leftover adapter factory removed, dead userId branches and
unused exports deleted.
Part 4 of the stacked series; tree is byte-identical to the verified
add-quiz-item-type branch.
---
.../ai/workspace-tool-result-adapters.ts | 55 +++++++------------
.../workspaces/content/entry-rich-text.ts | 10 +---
.../content/workspace-content-contract.ts | 2 +-
.../content/workspace-content-reader.ts | 34 ++++++++++--
.../flashcards/flashcard-content.ts | 16 ++----
.../workspaces/flashcards/flashcard-edits.ts | 21 ++++---
.../flashcards/flashcard-persistence.ts | 10 +---
.../flashcards/flashcard-study-session.ts | 9 +--
.../workspace-tool-surface.test.ts.snap | 2 +-
.../operations/workspace-tool-schemas.ts | 6 +-
.../workspaces/quizzes/quiz-content.ts | 30 +++-------
.../workspaces/quizzes/quiz-edits.test.ts | 8 +--
src/features/workspaces/quizzes/quiz-edits.ts | 23 ++++----
.../workspaces/quizzes/quiz-persistence.ts | 6 +-
.../workspaces/quizzes/quiz-study-session.ts | 9 +--
src/lib/shuffle.ts | 10 ++++
16 files changed, 108 insertions(+), 143 deletions(-)
create mode 100644 src/lib/shuffle.ts
diff --git a/src/features/workspaces/ai/workspace-tool-result-adapters.ts b/src/features/workspaces/ai/workspace-tool-result-adapters.ts
index 930c048c..043426a8 100644
--- a/src/features/workspaces/ai/workspace-tool-result-adapters.ts
+++ b/src/features/workspaces/ai/workspace-tool-result-adapters.ts
@@ -1,5 +1,4 @@
import type { JSONValue } from "ai";
-import { z } from "zod";
import { workspaceReadItemsOutputSchema } from "#/features/workspaces/content/workspace-content-contract";
import { createWorkspaceReadItemsModelOutput } from "#/features/workspaces/content/workspace-read-model-output";
@@ -13,41 +12,27 @@ import {
* the model needs. Addresses are already self-describing, so projection is
* only ever subtraction: internal item ids and app-side bookkeeping.
*/
-function defineWorkspaceToolResultAdapter(input: {
- outputSchema: TSchema;
- projectOutput: (output: z.output) => unknown;
-}) {
- return {
- projectOutput: (output: unknown) => {
- return input.projectOutput(input.outputSchema.parse(output)) as JSONValue;
- },
- };
-}
-
-const workspaceReadItemsResultAdapter = defineWorkspaceToolResultAdapter({
- outputSchema: workspaceReadItemsOutputSchema,
- projectOutput: createWorkspaceReadItemsModelOutput,
-});
-
-const workspaceCreateItemsResultAdapter = defineWorkspaceToolResultAdapter({
- outputSchema: workspaceCreateItemsOutputSchema,
- projectOutput: (output) => ({
- failed: output.failed,
- items: output.items.map(({ itemId: _itemId, ...item }) => item),
- }),
-});
-
-// The operation output also carries the durable item id used by the app's
-// review controls. Keep the model-facing receipt limited to actionable counts.
-const workspaceEditItemResultAdapter = defineWorkspaceToolResultAdapter({
- outputSchema: workspaceEditItemOutputSchema,
- projectOutput: ({ applied, failed, path }) => ({ applied, failed, path }),
-});
-
const workspaceToolResultAdapters = {
- workspace_create_items: workspaceCreateItemsResultAdapter,
- workspace_edit_item: workspaceEditItemResultAdapter,
- workspace_read_items: workspaceReadItemsResultAdapter,
+ workspace_create_items: {
+ projectOutput: (output: unknown): JSONValue => {
+ const { failed, items } = workspaceCreateItemsOutputSchema.parse(output);
+ return { failed, items: items.map(({ itemId: _itemId, ...item }) => item) } as JSONValue;
+ },
+ },
+ // The operation output also carries the durable item id used by the app's
+ // review controls. Keep the model-facing receipt limited to actionable counts.
+ workspace_edit_item: {
+ projectOutput: (output: unknown): JSONValue => {
+ const { applied, failed, path } = workspaceEditItemOutputSchema.parse(output);
+ return { applied, failed, path } as JSONValue;
+ },
+ },
+ workspace_read_items: {
+ projectOutput: (output: unknown): JSONValue =>
+ createWorkspaceReadItemsModelOutput(
+ workspaceReadItemsOutputSchema.parse(output),
+ ) as JSONValue,
+ },
} as const;
export function getWorkspaceToolResultAdapter(name: string) {
diff --git a/src/features/workspaces/content/entry-rich-text.ts b/src/features/workspaces/content/entry-rich-text.ts
index e89f6e1d..13c18137 100644
--- a/src/features/workspaces/content/entry-rich-text.ts
+++ b/src/features/workspaces/content/entry-rich-text.ts
@@ -1,9 +1,6 @@
import { z } from "zod";
-import {
- parseDocumentAiHtml,
- serializeTiptapDocumentToHtml,
-} from "#/features/workspaces/documents/document-ai-html";
+import { parseDocumentAiHtml } from "#/features/workspaces/documents/document-ai-html";
import {
coerceTiptapDocumentProjection,
type TiptapDocumentJson,
@@ -49,7 +46,6 @@ export function createEntryRichTextParser(messages: EntryRichTextMessages) {
}
return {
- assertEntryRichText,
parseEntryRichTextHtml(html: string): TiptapDocumentJson {
const document = parseDocumentAiHtml(html);
assertEntryRichText(document);
@@ -66,10 +62,6 @@ export function createEntryRichTextParser(messages: EntryRichTextMessages) {
};
}
-export function serializeEntryRichTextToHtml(entry: TiptapDocumentJson) {
- return serializeTiptapDocumentToHtml(entry);
-}
-
function visitRichTextValue(value: unknown, messages: EntryRichTextMessages) {
if (Array.isArray(value)) {
for (const entry of value) visitRichTextValue(entry, messages);
diff --git a/src/features/workspaces/content/workspace-content-contract.ts b/src/features/workspaces/content/workspace-content-contract.ts
index 95d204d9..e4f3afb6 100644
--- a/src/features/workspaces/content/workspace-content-contract.ts
+++ b/src/features/workspaces/content/workspace-content-contract.ts
@@ -35,7 +35,7 @@ const workspacePageRangeSchema = workspaceNumberRangeSchema.describe(
"Up to 20 physical pages from an extracted file, like 1, 3, 5-7, or 1,4-6.",
);
const workspaceEntryRangeSchema = workspaceNumberRangeSchema.describe(
- "Up to 20 entry numbers — document blocks, flashcards, or quiz questions — like 1, 3, 5-7, or 1,4-6.",
+ "Up to 20 entry numbers. Flashcards and quiz questions take lists like 1, 3, 5-7; document blocks take one contiguous range like 5-12.",
);
/**
diff --git a/src/features/workspaces/content/workspace-content-reader.ts b/src/features/workspaces/content/workspace-content-reader.ts
index 6119389a..2f965bd5 100644
--- a/src/features/workspaces/content/workspace-content-reader.ts
+++ b/src/features/workspaces/content/workspace-content-reader.ts
@@ -266,7 +266,14 @@ async function readFlashcards(
request: input.request,
targetEntryId: targetCardId,
});
- if (!selection.ok) return { code: selection.code, path: input.path, status: "failed" };
+ if (!selection.ok) {
+ return {
+ code: selection.code,
+ ...(selection.message ? { message: selection.message } : {}),
+ path: input.path,
+ status: "failed",
+ };
+ }
return {
cards: await Promise.all(
@@ -320,7 +327,14 @@ async function readQuiz(
request: input.request,
targetEntryId: targetQuestionId,
});
- if (!selection.ok) return { code: selection.code, path: input.path, status: "failed" };
+ if (!selection.ok) {
+ return {
+ code: selection.code,
+ ...(selection.message ? { message: selection.message } : {}),
+ path: input.path,
+ status: "failed",
+ };
+ }
return {
format: "html",
@@ -364,7 +378,15 @@ async function readQuiz(
type OrderedEntrySelection =
| { ok: true; selected: T[]; returned: number[] }
- | { ok: false; code: "invalid_selection" | "ref_not_found" };
+ | {
+ ok: false;
+ code:
+ | "invalid_selection"
+ | "page_range_out_of_range"
+ | "page_selection_too_large"
+ | "ref_not_found";
+ message?: string;
+ };
/**
* Shared selection for structured items: one targeted entry from an address,
@@ -391,7 +413,11 @@ function selectOrderedEntries(input: {
returned = parseWorkspacePageRange(request.range, entries.length);
} catch (error) {
if (error instanceof WorkspacePageSelectionError) {
- return { ok: false, code: "invalid_selection" };
+ return {
+ ok: false,
+ code: error.code,
+ message: `The item has ${entries.length} entries; request up to 20 of them per read.`,
+ };
}
throw error;
}
diff --git a/src/features/workspaces/flashcards/flashcard-content.ts b/src/features/workspaces/flashcards/flashcard-content.ts
index 4914f36f..aa404eff 100644
--- a/src/features/workspaces/flashcards/flashcard-content.ts
+++ b/src/features/workspaces/flashcards/flashcard-content.ts
@@ -1,8 +1,5 @@
-import {
- createEntryRichTextParser,
- entryRichTextHtmlSchema,
- serializeEntryRichTextToHtml,
-} from "#/features/workspaces/content/entry-rich-text";
+import { createEntryRichTextParser } from "#/features/workspaces/content/entry-rich-text";
+import { serializeTiptapDocumentToHtml } from "#/features/workspaces/documents/document-ai-html";
import type { TiptapDocumentJson } from "#/features/workspaces/documents/tiptap-document";
import {
createWorkspaceEntryId,
@@ -12,7 +9,6 @@ import { sha256Base64UrlText } from "#/lib/binary";
import { isRecord } from "#/lib/record";
export const FLASHCARD_SET_VERSION = 1;
-export const flashcardSideHtmlSchema = entryRichTextHtmlSchema;
const flashcardIdSchema = workspaceEntryIdSchema;
export interface Flashcard {
@@ -93,10 +89,6 @@ export function stringifyFlashcardSetContent(content: FlashcardSetContent) {
return `${JSON.stringify(content)}\n`;
}
-export function serializeFlashcardSideToHtml(side: TiptapDocumentJson) {
- return serializeEntryRichTextToHtml(side);
-}
-
export async function createFlashcardRevision(card: Flashcard) {
return (await sha256Base64UrlText(JSON.stringify({ front: card.front, back: card.back }))).slice(
0,
@@ -107,7 +99,7 @@ export async function createFlashcardRevision(card: Flashcard) {
export function serializeFlashcardSetToHtml(content: FlashcardSetContent): FlashcardHtmlCard[] {
return content.cards.map((card) => ({
id: card.id,
- front: serializeFlashcardSideToHtml(card.front),
- back: serializeFlashcardSideToHtml(card.back),
+ front: serializeTiptapDocumentToHtml(card.front),
+ back: serializeTiptapDocumentToHtml(card.back),
}));
}
diff --git a/src/features/workspaces/flashcards/flashcard-edits.ts b/src/features/workspaces/flashcards/flashcard-edits.ts
index e96aa455..ba7be66e 100644
--- a/src/features/workspaces/flashcards/flashcard-edits.ts
+++ b/src/features/workspaces/flashcards/flashcard-edits.ts
@@ -8,12 +8,12 @@ import {
import { replaceUniqueText } from "#/features/workspaces/content/replace-unique-text";
import {
createFlashcardRevision,
- flashcardSideHtmlSchema,
parseFlashcardSideHtml,
- serializeFlashcardSideToHtml,
type Flashcard,
type FlashcardSetContent,
} from "#/features/workspaces/flashcards/flashcard-content";
+import { entryRichTextHtmlSchema } from "#/features/workspaces/content/entry-rich-text";
+import { serializeTiptapDocumentToHtml } from "#/features/workspaces/documents/document-ai-html";
import {
createWorkspaceEntryId,
workspaceUnitRefInputSchema,
@@ -25,15 +25,15 @@ export const flashcardEditSchema = z.union([
z.strictObject({
op: z.enum(["insert_before", "insert_after"]),
ref: workspaceUnitRefInputSchema,
- front: flashcardSideHtmlSchema,
- back: flashcardSideHtmlSchema,
+ front: entryRichTextHtmlSchema,
+ back: entryRichTextHtmlSchema,
}),
z
.strictObject({
op: z.literal("update"),
ref: workspaceUnitRefInputSchema,
- front: flashcardSideHtmlSchema.optional(),
- back: flashcardSideHtmlSchema.optional(),
+ front: entryRichTextHtmlSchema.optional(),
+ back: entryRichTextHtmlSchema.optional(),
})
.refine((value) => value.front !== undefined || value.back !== undefined, {
message: "Provide a new front or back.",
@@ -41,8 +41,8 @@ export const flashcardEditSchema = z.union([
z.strictObject({
op: z.literal("replace"),
ref: workspaceUnitRefInputSchema,
- front: flashcardSideHtmlSchema,
- back: flashcardSideHtmlSchema,
+ front: entryRichTextHtmlSchema,
+ back: entryRichTextHtmlSchema,
}),
z.strictObject({
op: z.literal("replace_text"),
@@ -70,12 +70,11 @@ export const flashcardEditSchema = z.union([
]);
export type FlashcardEdit = z.output;
-export type FlashcardEditTarget = OrderedEntryEditTarget;
export async function applyFlashcardEdits(
content: FlashcardSetContent,
edits: FlashcardEdit[],
- targets: ReadonlyMap,
+ targets: ReadonlyMap,
) {
const result = await applyOrderedEntryEdits({
entries: content.cards,
@@ -122,7 +121,7 @@ function reviseCard(card: Flashcard, edit: FlashcardEdit): Flashcard {
}
if (edit.op === "replace_text") {
const replaced = replaceUniqueText(
- serializeFlashcardSideToHtml(card[edit.side]),
+ serializeTiptapDocumentToHtml(card[edit.side]),
edit.find,
edit.replace,
);
diff --git a/src/features/workspaces/flashcards/flashcard-persistence.ts b/src/features/workspaces/flashcards/flashcard-persistence.ts
index ceb80dd5..0c17c9d3 100644
--- a/src/features/workspaces/flashcards/flashcard-persistence.ts
+++ b/src/features/workspaces/flashcards/flashcard-persistence.ts
@@ -14,17 +14,9 @@ import {
withWorkspaceTransaction,
} from "#/features/workspaces/persistence/workspace-postgres-support";
import { notifyWorkspaceRoom } from "#/features/workspaces/realtime/workspace-room-notifier";
-import { assertCanReadWorkspace } from "#/features/workspaces/server/permissions";
-export async function readFlashcardSet(input: {
- itemId: string;
- workspaceId: string;
- userId?: string;
-}) {
+export async function readFlashcardSet(input: { itemId: string; workspaceId: string }) {
return await withDb(async (db) => {
- if (input.userId) {
- await assertCanReadWorkspace(db, { workspaceId: input.workspaceId, userId: input.userId });
- }
const [row] = await db
.select({ content: workspaceItemContents.content })
.from(workspaceItems)
diff --git a/src/features/workspaces/flashcards/flashcard-study-session.ts b/src/features/workspaces/flashcards/flashcard-study-session.ts
index a6479147..3917da0d 100644
--- a/src/features/workspaces/flashcards/flashcard-study-session.ts
+++ b/src/features/workspaces/flashcards/flashcard-study-session.ts
@@ -4,6 +4,7 @@ import type {
FlashcardStudyRating,
FlashcardStudyState,
} from "#/features/workspaces/flashcards/flashcard-study-state";
+import { shuffleInPlace } from "#/lib/shuffle";
export type FlashcardStudyMode = "all" | "missed";
@@ -46,11 +47,5 @@ export function createFlashcardStudyQueue(
}
}
- if (!input.shuffled) return cardIds;
-
- for (let index = cardIds.length - 1; index > 0; index -= 1) {
- const swapIndex = Math.floor(random() * (index + 1));
- [cardIds[index], cardIds[swapIndex]] = [cardIds[swapIndex]!, cardIds[index]!];
- }
- return cardIds;
+ return input.shuffled ? shuffleInPlace(cardIds, random) : cardIds;
}
diff --git a/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap b/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap
index 5f94c410..916c1cb2 100644
--- a/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap
+++ b/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap
@@ -1157,7 +1157,7 @@ exports[`workspace tool surface > workspace_read_items input schema is stable 1`
"type": "string",
},
"range": {
- "description": "Up to 20 entry numbers — document blocks, flashcards, or quiz questions — like 1, 3, 5-7, or 1,4-6.",
+ "description": "Up to 20 entry numbers. Flashcards and quiz questions take lists like 1, 3, 5-7; document blocks take one contiguous range like 5-12.",
"minLength": 1,
"pattern": "^\\d+(?:\\s*-\\s*\\d+)?(?:\\s*,\\s*\\d+(?:\\s*-\\s*\\d+)?)*$",
"type": "string",
diff --git a/src/features/workspaces/operations/workspace-tool-schemas.ts b/src/features/workspaces/operations/workspace-tool-schemas.ts
index c6f02e4b..249a88d6 100644
--- a/src/features/workspaces/operations/workspace-tool-schemas.ts
+++ b/src/features/workspaces/operations/workspace-tool-schemas.ts
@@ -23,8 +23,8 @@ import {
} from "#/features/workspaces/documents/document-ai-edits";
import { workspaceFileAssetKindSchema } from "#/features/workspaces/model/workspace-file";
import { flashcardEditSchema } from "#/features/workspaces/flashcards/flashcard-edits";
-import { flashcardSideHtmlSchema } from "#/features/workspaces/flashcards/flashcard-content";
import { quizEditSchema, quizQuestionInputSchema } from "#/features/workspaces/quizzes/quiz-edits";
+import { entryRichTextHtmlSchema } from "#/features/workspaces/content/entry-rich-text";
export { workspaceReadItemsInputSchema, workspaceReadItemsOutputSchema };
@@ -240,8 +240,8 @@ export const workspaceCreateItemsInputSchema = z.object({
cards: z
.array(
z.object({
- front: flashcardSideHtmlSchema.describe("HTML shown before the card flips."),
- back: flashcardSideHtmlSchema.describe("HTML shown after the card flips."),
+ front: entryRichTextHtmlSchema.describe("HTML shown before the card flips."),
+ back: entryRichTextHtmlSchema.describe("HTML shown after the card flips."),
}),
)
.min(1)
diff --git a/src/features/workspaces/quizzes/quiz-content.ts b/src/features/workspaces/quizzes/quiz-content.ts
index e8b9d3ac..f78fa9f9 100644
--- a/src/features/workspaces/quizzes/quiz-content.ts
+++ b/src/features/workspaces/quizzes/quiz-content.ts
@@ -1,8 +1,5 @@
-import {
- createEntryRichTextParser,
- entryRichTextHtmlSchema,
- serializeEntryRichTextToHtml,
-} from "#/features/workspaces/content/entry-rich-text";
+import { createEntryRichTextParser } from "#/features/workspaces/content/entry-rich-text";
+import { serializeTiptapDocumentToHtml } from "#/features/workspaces/documents/document-ai-html";
import type { TiptapDocumentJson } from "#/features/workspaces/documents/tiptap-document";
import {
createWorkspaceEntryId,
@@ -10,9 +7,9 @@ import {
} from "#/features/workspaces/locations/workspace-location";
import { sha256Base64UrlText } from "#/lib/binary";
import { isRecord } from "#/lib/record";
+import { shuffleInPlace } from "#/lib/shuffle";
export const QUIZ_SET_VERSION = 1;
-export const quizRichTextHtmlSchema = entryRichTextHtmlSchema;
const quizIdSchema = workspaceEntryIdSchema;
export const QUIZ_QUESTION_MIN_DISTRACTORS = 1;
@@ -182,10 +179,6 @@ export function stringifyQuizSetContent(content: QuizSetContent) {
return `${JSON.stringify(content)}\n`;
}
-export function serializeQuizRichTextToHtml(value: TiptapDocumentJson) {
- return serializeEntryRichTextToHtml(value);
-}
-
export async function createQuizQuestionRevision(question: QuizQuestion) {
return (
await sha256Base64UrlText(
@@ -209,32 +202,23 @@ export interface QuizHtmlQuestion {
export function serializeQuizSetToHtml(content: QuizSetContent): QuizHtmlQuestion[] {
return content.questions.map((question) => ({
id: question.id,
- question: serializeQuizRichTextToHtml(question.question),
+ question: serializeTiptapDocumentToHtml(question.question),
options: question.options.map((option) => ({
id: option.id,
- text: serializeQuizRichTextToHtml(option.text),
+ text: serializeTiptapDocumentToHtml(option.text),
correct: option.id === question.correctOptionId,
})),
- explanation: serializeQuizRichTextToHtml(question.explanation),
+ explanation: serializeTiptapDocumentToHtml(question.explanation),
}));
}
function assertDistinctOptions(options: QuizOption[]) {
const seen = new Set();
for (const option of options) {
- const key = serializeEntryRichTextToHtml(option.text);
+ const key = serializeTiptapDocumentToHtml(option.text);
if (seen.has(key)) {
throw new Error("Every option in a question must be distinct.");
}
seen.add(key);
}
}
-
-function shuffleInPlace(values: T[]) {
- for (let i = values.length - 1; i > 0; i--) {
- const j = Math.floor(Math.random() * (i + 1));
- const a = values[i]!;
- values[i] = values[j]!;
- values[j] = a;
- }
-}
diff --git a/src/features/workspaces/quizzes/quiz-edits.test.ts b/src/features/workspaces/quizzes/quiz-edits.test.ts
index 433e852a..5b4f4593 100644
--- a/src/features/workspaces/quizzes/quiz-edits.test.ts
+++ b/src/features/workspaces/quizzes/quiz-edits.test.ts
@@ -3,9 +3,9 @@ import { describe, expect, it } from "vitest";
import {
createQuizQuestionRevision,
createQuizSetFromInputs,
- serializeQuizRichTextToHtml,
type QuizQuestion,
} from "#/features/workspaces/quizzes/quiz-content";
+import { serializeTiptapDocumentToHtml } from "#/features/workspaces/documents/document-ai-html";
import { applyQuizEdits, quizEditSchema } from "#/features/workspaces/quizzes/quiz-edits";
const firstQuestion = {
@@ -50,11 +50,11 @@ describe("applyQuizEdits", () => {
expect(result.applied).toBe(5);
expect(result.content.questions).toHaveLength(3);
const revisedSecond = result.content.questions.find((entry) => entry.id === second!.id)!;
- expect(serializeQuizRichTextToHtml(revisedSecond.explanation)).toBe(
+ expect(serializeTiptapDocumentToHtml(revisedSecond.explanation)).toBe(
"Updated explanation.
",
);
expect(
- revisedSecond.options.map((option) => serializeQuizRichTextToHtml(option.text)),
+ revisedSecond.options.map((option) => serializeTiptapDocumentToHtml(option.text)),
).toContain("The mitochondria
");
// replace keeps the id so citations to the question survive re-authoring.
expect(result.content.questions.some((entry) => entry.id === first!.id)).toBe(true);
@@ -82,7 +82,7 @@ describe("applyQuizEdits", () => {
expect(result.failed).toEqual([]);
const revised = result.content.questions[0]!;
const correct = revised.options.find((option) => option.id === revised.correctOptionId)!;
- expect(serializeQuizRichTextToHtml(correct.text)).toBe("Readily usable energy
");
+ expect(serializeTiptapDocumentToHtml(correct.text)).toBe("Readily usable energy
");
});
it("rejects option fixes that match more than one option", async () => {
diff --git a/src/features/workspaces/quizzes/quiz-edits.ts b/src/features/workspaces/quizzes/quiz-edits.ts
index ccf0c035..d111162e 100644
--- a/src/features/workspaces/quizzes/quiz-edits.ts
+++ b/src/features/workspaces/quizzes/quiz-edits.ts
@@ -10,30 +10,30 @@ import {
createQuizQuestionRevision,
materializeQuizQuestion,
parseQuizRichTextHtml,
- quizRichTextHtmlSchema,
QUIZ_QUESTION_MAX_DISTRACTORS,
QUIZ_QUESTION_MIN_DISTRACTORS,
- serializeQuizRichTextToHtml,
type QuizQuestion,
type QuizSetContent,
} from "#/features/workspaces/quizzes/quiz-content";
+import { entryRichTextHtmlSchema } from "#/features/workspaces/content/entry-rich-text";
+import { serializeTiptapDocumentToHtml } from "#/features/workspaces/documents/document-ai-html";
import { workspaceUnitRefInputSchema } from "#/features/workspaces/locations/workspace-location";
const editTextSchema = z.string().max(8_000);
const authoredQuestionFields = {
- question: quizRichTextHtmlSchema.describe("HTML question stem."),
- correctAnswer: quizRichTextHtmlSchema.describe(
+ question: entryRichTextHtmlSchema.describe("HTML question stem."),
+ correctAnswer: entryRichTextHtmlSchema.describe(
"HTML for the single correct option. Never mark it in the stem; its final position is shuffled server-side.",
),
distractors: z
- .array(quizRichTextHtmlSchema)
+ .array(entryRichTextHtmlSchema)
.min(QUIZ_QUESTION_MIN_DISTRACTORS)
.max(QUIZ_QUESTION_MAX_DISTRACTORS)
.describe(
"HTML for each incorrect option: strictly wrong, plausible, and grounded in a specific misconception. Use 3 for a standard question, 1 for true/false.",
),
- explanation: quizRichTextHtmlSchema.describe(
+ explanation: entryRichTextHtmlSchema.describe(
"Short HTML explanation of why the correct answer is right, touching on why the others are not.",
),
};
@@ -51,8 +51,8 @@ export const quizEditSchema = z.union([
.strictObject({
op: z.literal("update"),
ref: workspaceUnitRefInputSchema,
- question: quizRichTextHtmlSchema.optional().describe("New HTML question stem."),
- explanation: quizRichTextHtmlSchema.optional().describe("New HTML explanation."),
+ question: entryRichTextHtmlSchema.optional().describe("New HTML question stem."),
+ explanation: entryRichTextHtmlSchema.optional().describe("New HTML explanation."),
})
.refine((value) => value.question !== undefined || value.explanation !== undefined, {
message: "Provide a new question or explanation.",
@@ -90,12 +90,11 @@ export const quizEditSchema = z.union([
]);
export type QuizEdit = z.output;
-export type QuizEditTarget = OrderedEntryEditTarget;
export async function applyQuizEdits(
content: QuizSetContent,
edits: QuizEdit[],
- targets: ReadonlyMap,
+ targets: ReadonlyMap,
) {
const result = await applyOrderedEntryEdits({
entries: content.questions,
@@ -152,7 +151,7 @@ function replaceQuestionText(
let matchedTwiceInOne = false;
for (const [index, option] of question.options.entries()) {
const replaced = replaceUniqueText(
- serializeQuizRichTextToHtml(option.text),
+ serializeTiptapDocumentToHtml(option.text),
edit.find,
edit.replace,
);
@@ -181,7 +180,7 @@ function replaceQuestionText(
}
const replaced = replaceUniqueText(
- serializeQuizRichTextToHtml(question[edit.field]),
+ serializeTiptapDocumentToHtml(question[edit.field]),
edit.find,
edit.replace,
);
diff --git a/src/features/workspaces/quizzes/quiz-persistence.ts b/src/features/workspaces/quizzes/quiz-persistence.ts
index 1932be9d..dd54bb89 100644
--- a/src/features/workspaces/quizzes/quiz-persistence.ts
+++ b/src/features/workspaces/quizzes/quiz-persistence.ts
@@ -14,13 +14,9 @@ import {
withWorkspaceTransaction,
} from "#/features/workspaces/persistence/workspace-postgres-support";
import { notifyWorkspaceRoom } from "#/features/workspaces/realtime/workspace-room-notifier";
-import { assertCanReadWorkspace } from "#/features/workspaces/server/permissions";
-export async function readQuizSet(input: { itemId: string; workspaceId: string; userId?: string }) {
+export async function readQuizSet(input: { itemId: string; workspaceId: string }) {
return await withDb(async (db) => {
- if (input.userId) {
- await assertCanReadWorkspace(db, { workspaceId: input.workspaceId, userId: input.userId });
- }
const [row] = await db
.select({ content: workspaceItemContents.content })
.from(workspaceItems)
diff --git a/src/features/workspaces/quizzes/quiz-study-session.ts b/src/features/workspaces/quizzes/quiz-study-session.ts
index bf752930..8cb4c27f 100644
--- a/src/features/workspaces/quizzes/quiz-study-session.ts
+++ b/src/features/workspaces/quizzes/quiz-study-session.ts
@@ -4,6 +4,7 @@ import {
type QuizStudyProgress,
type QuizStudyState,
} from "#/features/workspaces/quizzes/quiz-study-state";
+import { shuffleInPlace } from "#/lib/shuffle";
export type QuizStudyMode = "all" | "missed";
@@ -26,13 +27,7 @@ export function createQuizStudyQueue(
}
}
- if (!input.shuffled) return questionIds;
-
- for (let index = questionIds.length - 1; index > 0; index -= 1) {
- const swapIndex = Math.floor(random() * (index + 1));
- [questionIds[index], questionIds[swapIndex]] = [questionIds[swapIndex]!, questionIds[index]!];
- }
- return questionIds;
+ return input.shuffled ? shuffleInPlace(questionIds, random) : questionIds;
}
/** What the AI's live view context says about the open quiz. */
diff --git a/src/lib/shuffle.ts b/src/lib/shuffle.ts
new file mode 100644
index 00000000..a94c31cf
--- /dev/null
+++ b/src/lib/shuffle.ts
@@ -0,0 +1,10 @@
+/** Fisher–Yates, in place. Pass a seeded `random` for deterministic tests. */
+export function shuffleInPlace(values: T[], random: () => number = Math.random) {
+ for (let index = values.length - 1; index > 0; index -= 1) {
+ const swapIndex = Math.floor(random() * (index + 1));
+ const value = values[index]!;
+ values[index] = values[swapIndex]!;
+ values[swapIndex] = value;
+ }
+ return values;
+}
From 12fc7e66d15dcbcb93dd9124de0e62b42187da5f Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Sat, 15 Aug 2026 14:56:21 -0400
Subject: [PATCH 05/14] refactor(workspaces): share study session chrome
between viewers
The flashcard and quiz viewers each carried their own copy of the same
pieces: a read-only Tiptap render, the amber "ask AI" button, the
prev/next arrows, and the progress strip. Same look, four chances to
drift.
Extracts them into components/study: StudyRichText, StudyAiActionButton,
StudyNavButton, and StudyProgressStrip, whose segments now carry a tone
so each item type maps its own state onto one strip.
---
.../components/flashcards/FlashcardViewer.tsx | 175 +++++-------------
.../components/study/StudyProgressStrip.tsx | 68 +++++++
.../components/study/StudyRichText.tsx | 36 ++++
.../components/study/StudySessionControls.tsx | 66 +++++++
4 files changed, 214 insertions(+), 131 deletions(-)
create mode 100644 src/features/workspaces/components/study/StudyProgressStrip.tsx
create mode 100644 src/features/workspaces/components/study/StudyRichText.tsx
create mode 100644 src/features/workspaces/components/study/StudySessionControls.tsx
diff --git a/src/features/workspaces/components/flashcards/FlashcardViewer.tsx b/src/features/workspaces/components/flashcards/FlashcardViewer.tsx
index d7fbaf52..efe4f5e1 100644
--- a/src/features/workspaces/components/flashcards/FlashcardViewer.tsx
+++ b/src/features/workspaces/components/flashcards/FlashcardViewer.tsx
@@ -1,16 +1,22 @@
import { useQuery } from "@tanstack/react-query";
-import type { JSONContent } from "@tiptap/core";
-import { EditorContent, useEditor } from "@tiptap/react";
-import { Check, ChevronLeft, ChevronRight, Lightbulb, X } from "lucide-react";
+import { Check, X } from "lucide-react";
import { domAnimation, LazyMotion, m, MotionConfig } from "motion/react";
import { type ReactNode, useCallback, useEffect, useMemo, useState } from "react";
import { Button } from "#/components/ui/button";
import { Skeleton } from "#/components/ui/skeleton";
import { sendComposerPrompt } from "#/features/workspaces/composer/workspace-composer-actions";
+import {
+ StudyProgressStrip,
+ type StudyProgressTone,
+} from "#/features/workspaces/components/study/StudyProgressStrip";
+import { StudyRichText } from "#/features/workspaces/components/study/StudyRichText";
+import {
+ StudyAiActionButton,
+ StudyNavButton,
+} from "#/features/workspaces/components/study/StudySessionControls";
import { StudyToolbar } from "#/features/workspaces/components/study/StudyToolbar";
import { useWorkspaceItemToolbar } from "#/features/workspaces/components/WorkspaceItemToolbarSlot";
-import { getTiptapDocumentBaseExtensions } from "#/features/workspaces/documents/tiptap-extensions";
import type { TiptapDocumentJson } from "#/features/workspaces/documents/tiptap-document";
import {
flashcardViewerQueryOptions,
@@ -573,7 +579,8 @@ function FlashcardStudySurface({
label="Front"
content={currentCard.front}
action={
-
sendComposerPrompt(
@@ -590,7 +597,8 @@ function FlashcardStudySurface({
label="Back"
content={currentCard.back}
action={
-
sendComposerPrompt(
@@ -607,30 +615,28 @@ function FlashcardStudySurface({
- {
+ const { label, tone } = describeFlashcardRating(
+ studyState.cards[card.id]?.lastRating,
+ );
+ return { id: card.id, label: `Card ${index + 1}: ${label}`, tone };
+ })}
/>
{gotItCount + missedCount} reviewed
-
+ />
-
+ />
{currentIndex + 1} of {studyCards.length}
@@ -687,66 +688,6 @@ function FlashcardStudySurface({
);
}
-function FlashcardStatusStrip({
- cards,
- currentIndex,
- gotItCount,
- missedCount,
- onSelect,
- reviewsByCardId,
-}: {
- cards: Flashcard[];
- currentIndex: number;
- gotItCount: number;
- missedCount: number;
- onSelect: (index: number) => void;
- reviewsByCardId: FlashcardStudyState["cards"];
-}) {
- const unseenCount = cards.length - gotItCount - missedCount;
- const gap = cards.length <= 50 ? 3 : cards.length <= 120 ? 2 : cards.length <= 300 ? 1 : 0;
-
- return (
-
- {cards.map((card, index) => {
- const rating = reviewsByCardId[card.id]?.lastRating;
- const status = getFlashcardRatingLabel(rating);
- return (
-
- );
- })}
-
- );
-}
-
function getStudyCards(cardIds: string[], cardsById: ReadonlyMap): Flashcard[] {
const cards: Flashcard[] = [];
for (const cardId of cardIds) {
@@ -756,18 +697,21 @@ function getStudyCards(cardIds: string[], cardsById: ReadonlyMap 500 ? "is-very-dense" : textLength > 220 ? "is-dense" : undefined;
- const editor = useEditor(
- {
- content: content as unknown as JSONContent,
- editable: false,
- immediatelyRender: false,
- extensions: getTiptapDocumentBaseExtensions(),
- editorProps: {
- attributes: {
- class: cn(
- "workspace-document-prose workspace-flashcard-prose outline-none",
- densityClass,
- ),
- },
- },
- },
- [content],
- );
return (
{action}
-
+ sendComposerPrompt(
+ item.workspaceId,
+ `Give me a helpful hint for question ${sourceQuestionNumber} in “${itemPath}” without revealing the answer.`,
+ )
+ }
+ />
+ ) : null}
+
+
-
- {currentQuestion.options.map((option, optionIndex) => {
- const isSelected = answer?.selectedOptionId === option.id;
- const isCorrectOption = option.id === currentQuestion.correctOptionId;
- const graded = answer !== undefined;
- return (
-
- );
- })}
-
+
+ {currentQuestion.options.map((option, optionIndex) => {
+ const isSelected = option.id === selectedOptionId;
+ const isCorrectOption = option.id === currentQuestion.correctOptionId;
+ const previousOption = currentQuestion.options[optionIndex - 1];
+ return (
+
+
+ sendComposerPrompt(
+ item.workspaceId,
+ `Explain the answer to question ${sourceQuestionNumber} in “${itemPath}” in more depth.`,
+ )
+ }
+ />
+
+ {
+ const questionAnswer = getQuizAnswer(question, studyState);
+ const questionCorrect = questionAnswer?.selectedOptionId === question.correctOptionId;
+ return {
+ id: question.id,
+ label: `Question ${index + 1}: ${
+ !questionAnswer ? "Unanswered" : questionCorrect ? "Correct" : "Missed"
+ }`,
+ tone: !questionAnswer ? "unseen" : questionCorrect ? "correct" : "missed",
+ };
+ })}
+ />
+
+
+ {quizProgress.answeredCount} answered
+
+
+ goTo(currentIndex - 1)}
+ />
+
+ {currentIndex + 1} of {studyQuestions.length}
+
+ goTo(currentIndex + 1)}
+ />
+
+ {graded ? (
+
+ ) : (
+
+ )}
+
-
+
);
}
function QuizRichText({ content, compact }: { content: TiptapDocumentJson; compact?: boolean }) {
- const editor = useEditor(
- {
- content: content as unknown as JSONContent,
- editable: false,
- immediatelyRender: false,
- extensions: getTiptapDocumentBaseExtensions(),
- editorProps: {
- attributes: {
- class: cn("workspace-document-prose outline-none", compact && "text-sm"),
- },
- },
- },
- [content],
+ return (
+ Heading
", back: "A
" }]),
- ).toThrow("Flashcards do not support heading content yet.");
+ ).toThrow("Flashcard content cannot contain heading nodes.");
});
it("rejects empty sets and malformed stored rich text", () => {
diff --git a/src/features/workspaces/flashcards/flashcard-content.ts b/src/features/workspaces/flashcards/flashcard-content.ts
index aa404eff..baed067d 100644
--- a/src/features/workspaces/flashcards/flashcard-content.ts
+++ b/src/features/workspaces/flashcards/flashcard-content.ts
@@ -1,4 +1,7 @@
-import { createEntryRichTextParser } from "#/features/workspaces/content/entry-rich-text";
+import {
+ parseEntryRichTextHtml,
+ parseStoredEntryRichText,
+} from "#/features/workspaces/content/entry-rich-text";
import { serializeTiptapDocumentToHtml } from "#/features/workspaces/documents/document-ai-html";
import type { TiptapDocumentJson } from "#/features/workspaces/documents/tiptap-document";
import {
@@ -28,12 +31,6 @@ interface FlashcardHtmlCard {
back: string;
}
-const flashcardRichText = createEntryRichTextParser({
- invalidStored: "Flashcard content contains invalid rich text.",
- unsupportedMark: "Flashcard content contains an unsupported text mark.",
- unsupportedNode: (nodeType) => `Flashcards do not support ${nodeType} content yet.`,
-});
-
export function createFlashcardSetFromHtml(cards: Array<{ front: string; back: string }>) {
if (cards.length === 0) throw new Error("A flashcard set needs at least one card.");
return {
@@ -47,7 +44,7 @@ export function createFlashcardSetFromHtml(cards: Array<{ front: string; back: s
}
export function parseFlashcardSideHtml(html: string) {
- return flashcardRichText.parseEntryRichTextHtml(html);
+ return parseEntryRichTextHtml(html, "Flashcard");
}
export function parseFlashcardSetContent(content: string | null): FlashcardSetContent {
@@ -77,8 +74,8 @@ export function parseFlashcardSetContent(content: string | null): FlashcardSetCo
}
seenIds.add(cardId.data);
- const front = flashcardRichText.parseStoredEntryRichText(card.front);
- const back = flashcardRichText.parseStoredEntryRichText(card.back);
+ const front = parseStoredEntryRichText(card.front, "Flashcard");
+ const back = parseStoredEntryRichText(card.back, "Flashcard");
return { id: cardId.data, front, back };
});
diff --git a/src/features/workspaces/quizzes/quiz-content.test.ts b/src/features/workspaces/quizzes/quiz-content.test.ts
index f2aadd31..2c8fe8a0 100644
--- a/src/features/workspaces/quizzes/quiz-content.test.ts
+++ b/src/features/workspaces/quizzes/quiz-content.test.ts
@@ -49,7 +49,7 @@ describe("materializeQuizQuestion", () => {
it("rejects content outside the entry rich-text dialect", () => {
expect(() =>
materializeQuizQuestion({ ...atpQuestion, question: "Heading stem
" }),
- ).toThrow("Quizzes do not support heading content yet.");
+ ).toThrow("Quiz content cannot contain heading nodes.");
});
});
diff --git a/src/features/workspaces/quizzes/quiz-content.ts b/src/features/workspaces/quizzes/quiz-content.ts
index f78fa9f9..f9428168 100644
--- a/src/features/workspaces/quizzes/quiz-content.ts
+++ b/src/features/workspaces/quizzes/quiz-content.ts
@@ -1,4 +1,7 @@
-import { createEntryRichTextParser } from "#/features/workspaces/content/entry-rich-text";
+import {
+ parseEntryRichTextHtml,
+ parseStoredEntryRichText,
+} from "#/features/workspaces/content/entry-rich-text";
import { serializeTiptapDocumentToHtml } from "#/features/workspaces/documents/document-ai-html";
import type { TiptapDocumentJson } from "#/features/workspaces/documents/tiptap-document";
import {
@@ -52,14 +55,8 @@ export interface QuizQuestionInput {
explanation: string;
}
-const quizRichText = createEntryRichTextParser({
- invalidStored: "Quiz content contains invalid rich text.",
- unsupportedMark: "Quiz content contains an unsupported text mark.",
- unsupportedNode: (nodeType) => `Quizzes do not support ${nodeType} content yet.`,
-});
-
export function parseQuizRichTextHtml(html: string) {
- return quizRichText.parseEntryRichTextHtml(html);
+ return parseEntryRichTextHtml(html, "Quiz");
}
export function createQuizSetFromInputs(questions: QuizQuestionInput[]) {
@@ -87,13 +84,13 @@ export function materializeQuizQuestion(input: QuizQuestionInput): QuizQuestion
const correct = {
id: crypto.randomUUID(),
- text: quizRichText.parseEntryRichTextHtml(input.correctAnswer),
+ text: parseEntryRichTextHtml(input.correctAnswer, "Quiz"),
};
const options = [
correct,
...input.distractors.map((distractor) => ({
id: crypto.randomUUID(),
- text: quizRichText.parseEntryRichTextHtml(distractor),
+ text: parseEntryRichTextHtml(distractor, "Quiz"),
})),
];
assertDistinctOptions(options);
@@ -102,10 +99,10 @@ export function materializeQuizQuestion(input: QuizQuestionInput): QuizQuestion
return {
id: createWorkspaceEntryId("q"),
kind: "multiple_choice",
- question: quizRichText.parseEntryRichTextHtml(input.question),
+ question: parseEntryRichTextHtml(input.question, "Quiz"),
options,
correctOptionId: correct.id,
- explanation: quizRichText.parseEntryRichTextHtml(input.explanation),
+ explanation: parseEntryRichTextHtml(input.explanation, "Quiz"),
};
}
@@ -153,7 +150,7 @@ export function parseQuizSetContent(content: string | null): QuizSetContent {
throw new Error("Quiz content contains an invalid option ID.");
}
seenOptionIds.add(optionId.data);
- return { id: optionId.data, text: quizRichText.parseStoredEntryRichText(option.text) };
+ return { id: optionId.data, text: parseStoredEntryRichText(option.text, "Quiz") };
});
if (
typeof question.correctOptionId !== "string" ||
@@ -165,10 +162,10 @@ export function parseQuizSetContent(content: string | null): QuizSetContent {
return {
id: questionId.data,
kind: "multiple_choice" as const,
- question: quizRichText.parseStoredEntryRichText(question.question),
+ question: parseStoredEntryRichText(question.question, "Quiz"),
options,
correctOptionId: question.correctOptionId,
- explanation: quizRichText.parseStoredEntryRichText(question.explanation),
+ explanation: parseStoredEntryRichText(question.explanation, "Quiz"),
};
});
From 5f83e5c442e3e9cc6a7ada372fc909a43f400469 Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Sat, 15 Aug 2026 14:57:09 -0400
Subject: [PATCH 09/14] feat(workspaces): draw mermaid code blocks as diagrams
everywhere
Chat could already draw mermaid. Documents, flashcards, and quizzes
could not, which left diagrams out of exactly the surfaces that explain
things. A mermaid block is an ordinary code block, so cards and
questions get diagrams without opening their allowlist to widgets, which
stay documents-only.
AiChatMermaidDiagram becomes a shared MermaidDiagram taking isIncomplete
as a prop, since only chat can see a half-written fence, and caches
rendered SVGs so a card flipped back and forth does not re-render its
artwork. CodeBlockNodeView draws the diagram in place of the source and
selects the whole block on click, the way an image behaves. PDF export
drops mermaid blocks rather than printing authoring syntax.
Tool schemas gain one diagram instruction shared by all three item
types, plus a note that a diagram usually belongs in a quiz stem or
explanation, since one option taller than the rest hints at the answer.
---
.../code-block/mermaid-diagram.tsx} | 87 +++++++++++++++----
.../components/ai-chat/ai-chat-code-block.tsx | 11 ++-
.../code-block-shiki/CodeBlockNodeView.tsx | 40 ++++++++-
.../code-block-shiki/code-languages.ts | 10 +++
.../documents/code-block-shiki/highlighter.ts | 1 +
.../workspace-document-pdf-html.test.ts | 21 +++++
.../export/workspace-document-pdf-html.ts | 24 ++++-
.../workspace-tool-surface.test.ts.snap | 12 +--
.../operations/workspace-tool-schemas.ts | 14 ++-
src/styles.css | 15 ++++
10 files changed, 202 insertions(+), 33 deletions(-)
rename src/{features/workspaces/components/ai-chat/AiChatMermaidDiagram.tsx => components/code-block/mermaid-diagram.tsx} (80%)
diff --git a/src/features/workspaces/components/ai-chat/AiChatMermaidDiagram.tsx b/src/components/code-block/mermaid-diagram.tsx
similarity index 80%
rename from src/features/workspaces/components/ai-chat/AiChatMermaidDiagram.tsx
rename to src/components/code-block/mermaid-diagram.tsx
index 9519beb4..21a9723a 100644
--- a/src/features/workspaces/components/ai-chat/AiChatMermaidDiagram.tsx
+++ b/src/components/code-block/mermaid-diagram.tsx
@@ -1,6 +1,5 @@
import { Check, Copy, GitBranch, Maximize2, Minimize2, Minus, Plus } from "lucide-react";
import { useEffect, useId, useRef, useState } from "react";
-import { useIsCodeFenceIncomplete } from "streamdown";
import { useTheme } from "#/components/theme-provider";
import {
@@ -28,6 +27,24 @@ type MermaidRenderResult =
let mermaidRenderQueue = Promise.resolve();
+/**
+ * Rendered SVGs keyed by theme and source. Study surfaces mount the same
+ * diagram over and over — flipping a card back and forth, stepping through
+ * questions, or any edit that rebuilds the editor — and re-running mermaid
+ * each time would flash a placeholder over artwork the reader just saw.
+ * Cleared wholesale past a generous ceiling: an eviction policy would cost
+ * more than the few kilobytes it saves.
+ */
+const mermaidImageCache = new Map();
+const MAX_CACHED_DIAGRAMS = 64;
+
+function cacheMermaidImage(requestKey: string, image: MermaidImage) {
+ if (mermaidImageCache.size >= MAX_CACHED_DIAGRAMS) {
+ mermaidImageCache.clear();
+ }
+ mermaidImageCache.set(requestKey, image);
+}
+
function enqueueMermaidRender(input: { darkMode: boolean; id: string; source: string }) {
const render = mermaidRenderQueue.then(async () => {
const { default: mermaid } = await import("mermaid");
@@ -146,17 +163,30 @@ function useNearViewport() {
return { containerRef, isNearViewport };
}
-export function AiChatMermaidDiagram({ source }: { source: string }) {
- const isIncomplete = useIsCodeFenceIncomplete();
+/**
+ * Renders one mermaid source block as a diagram. Shared by chat, where the
+ * source streams in, and by document code blocks, where it arrives whole —
+ * hence `isIncomplete` as a prop rather than a hook: only chat can observe a
+ * half-written fence, and a document must not wait for a stream that has
+ * already ended.
+ */
+export function MermaidDiagram({
+ isIncomplete = false,
+ source,
+}: {
+ isIncomplete?: boolean;
+ source: string;
+}) {
const { resolvedTheme } = useTheme();
const reactId = useId();
const { containerRef, isNearViewport } = useNearViewport();
const requestKey = `${resolvedTheme}:${source}`;
const sourceIsTooLarge = source.length > MAX_MERMAID_SOURCE_LENGTH;
+ const cachedImage = mermaidImageCache.get(requestKey);
const [result, setResult] = useState(null);
useEffect(() => {
- if (!isNearViewport || isIncomplete || sourceIsTooLarge) {
+ if (!isNearViewport || isIncomplete || sourceIsTooLarge || cachedImage) {
return;
}
@@ -174,13 +204,15 @@ export function AiChatMermaidDiagram({ source }: { source: string }) {
return;
}
- setResult({ image: prepareMermaidImage(svg), requestKey, status: "ready" });
+ const image = prepareMermaidImage(svg);
+ cacheMermaidImage(requestKey, image);
+ setResult({ image, requestKey, status: "ready" });
} catch (error: unknown) {
if (cancelled) {
return;
}
- console.warn("[AiChatMermaidDiagram] Failed to render diagram", error);
+ console.warn("[MermaidDiagram] Failed to render diagram", error);
setResult({ requestKey, status: "error" });
}
})();
@@ -188,16 +220,39 @@ export function AiChatMermaidDiagram({ source }: { source: string }) {
return () => {
cancelled = true;
};
- }, [isIncomplete, isNearViewport, reactId, requestKey, resolvedTheme, source, sourceIsTooLarge]);
-
- const state: MermaidRenderResult | { status: "loading" } = sourceIsTooLarge
- ? { requestKey, status: "error" }
- : isIncomplete || result?.requestKey !== requestKey
- ? { status: "loading" }
- : result;
+ }, [
+ cachedImage,
+ isIncomplete,
+ isNearViewport,
+ reactId,
+ requestKey,
+ resolvedTheme,
+ source,
+ sourceIsTooLarge,
+ ]);
+
+ // A cache hit is read straight through to the render rather than copied
+ // into state, so a remount paints finished artwork on the first frame.
+ // This render's own result still outranks it: an ![]()
that failed to
+ // decode must not be answered with the cached image that just failed.
+ const state = ((): MermaidRenderResult | { status: "loading" } => {
+ if (sourceIsTooLarge) {
+ return { requestKey, status: "error" };
+ }
+ if (isIncomplete) {
+ return { status: "loading" };
+ }
+ if (result?.requestKey === requestKey) {
+ return result;
+ }
+ if (cachedImage) {
+ return { image: cachedImage, requestKey, status: "ready" };
+ }
+ return { status: "loading" };
+ })();
return (
-
+
{state.status === "loading" ? This diagram couldn’t be displayed, but the rest of the response is unaffected.
+ This diagram couldn’t be displayed. Its source is unchanged.
View diagram source
@@ -260,7 +315,7 @@ function MermaidDiagramCard({
const [zoom, setZoom] = useState(1);
const { copied, copy } = useCopyToClipboard({
onError: (error) => {
- console.warn("[AiChatMermaidDiagram] Failed to copy source", error);
+ console.warn("[MermaidDiagram] Failed to copy source", error);
},
});
diff --git a/src/features/workspaces/components/ai-chat/ai-chat-code-block.tsx b/src/features/workspaces/components/ai-chat/ai-chat-code-block.tsx
index fad3fcd1..4a8d30e8 100644
--- a/src/features/workspaces/components/ai-chat/ai-chat-code-block.tsx
+++ b/src/features/workspaces/components/ai-chat/ai-chat-code-block.tsx
@@ -2,6 +2,7 @@ import type { CSSProperties, HTMLAttributes, ReactNode } from "react";
import { isValidElement, useEffect, useState } from "react";
import type { ThemedToken } from "shiki/core";
import { ClientOnly } from "@tanstack/react-router";
+import { useIsCodeFenceIncomplete } from "streamdown";
import {
CodeBlockActions,
CodeBlockCopyButton,
@@ -13,10 +14,11 @@ import {
import {
getCodeLanguageLabel,
highlightCodeTokens,
+ isMermaidCodeLanguage,
normalizeCodeLanguage,
type SupportedCodeLanguage,
} from "#/features/workspaces/documents/code-block-shiki/highlighter";
-import { AiChatMermaidDiagram } from "#/features/workspaces/components/ai-chat/AiChatMermaidDiagram";
+import { MermaidDiagram } from "#/components/code-block/mermaid-diagram";
import { cn } from "#/lib/utils.ts";
// Shiki uses bitflags for font styles: 1=italic, 2=bold, 4=underline
@@ -358,6 +360,9 @@ export const MarkdownCodeBlock = ({
"data-block": dataBlock,
...props
}: MarkdownCodeBlockProps) => {
+ // Only chat can see a half-written fence, so the streaming state is read
+ // here and handed to the shared diagram rather than looked up inside it.
+ const isFenceIncomplete = useIsCodeFenceIncomplete();
const isBlock = dataBlock !== undefined;
if (!isBlock) {
@@ -375,10 +380,10 @@ export const MarkdownCodeBlock = ({
getLanguageFromClassName(className) ?? getLanguageFromClassName(node?.properties?.className);
const code = getTextContent(children).replace(/\n$/, "");
- if (rawLanguage?.toLowerCase() === "mermaid") {
+ if (isMermaidCodeLanguage(rawLanguage)) {
return (
-
);
}
diff --git a/src/features/workspaces/documents/code-block-shiki/CodeBlockNodeView.tsx b/src/features/workspaces/documents/code-block-shiki/CodeBlockNodeView.tsx
index 212ddfb7..cb7dac2c 100644
--- a/src/features/workspaces/documents/code-block-shiki/CodeBlockNodeView.tsx
+++ b/src/features/workspaces/documents/code-block-shiki/CodeBlockNodeView.tsx
@@ -13,18 +13,56 @@ import {
CodeBlockLanguageSelectorValue,
CodeBlockTitle,
} from "#/components/code-block/code-block-chrome";
+import { MermaidDiagram } from "#/components/code-block/mermaid-diagram";
import {
codeLanguageOptions,
getCodeLanguageLabel,
+ isMermaidCodeLanguage,
normalizeCodeLanguage,
type SupportedCodeLanguage,
} from "#/features/workspaces/documents/code-block-shiki/highlighter";
-export function CodeBlockNodeView({ node, updateAttributes }: ReactNodeViewProps) {
+export function CodeBlockNodeView({
+ editor,
+ getPos,
+ node,
+ selected,
+ updateAttributes,
+}: ReactNodeViewProps) {
const language = normalizeCodeLanguage(node.attrs.language as string | null);
const code = node.textContent;
const codeLanguage = language ?? "text";
+ /**
+ * A diagram is only ever the drawing, never the mermaid source that made
+ * it. Nobody hand-writes that syntax — the assistant authors and edits it —
+ * so a click selects the whole block to move or delete, the way an image
+ * behaves. The content stays mounted but hidden because ProseMirror still
+ * needs somewhere to keep the node's text.
+ */
+ if (isMermaidCodeLanguage(node.attrs.language as string | null)) {
+ return (
+ {
+ const position = getPos();
+ if (position !== undefined && editor.isEditable) {
+ // Focus first: a click on non-editable content leaves the
+ // editor blurred, and an unfocused selection ignores Backspace.
+ editor.chain().focus().setNodeSelection(position).run();
+ }
+ }}
+ >
+
+ );
+ }
+
return (
({ label, value }),
);
+/**
+ * Mermaid is deliberately not one of the languages above. It is never syntax
+ * highlighted, never offered in the language picker, and never read as source
+ * — every surface draws it instead — so registering a grammar for it would
+ * only ship a parser nothing looks at.
+ */
+export function isMermaidCodeLanguage(language: string | null | undefined) {
+ return language?.trim().toLowerCase() === "mermaid";
+}
+
export const supportedCodeFileExtensions = [
...new Set(codeLanguageDefinitionList.flatMap((definition) => definition.extensions ?? [])),
].sort((left, right) => left.localeCompare(right));
diff --git a/src/features/workspaces/documents/code-block-shiki/highlighter.ts b/src/features/workspaces/documents/code-block-shiki/highlighter.ts
index 26d4c3e7..4fe9a7a9 100644
--- a/src/features/workspaces/documents/code-block-shiki/highlighter.ts
+++ b/src/features/workspaces/documents/code-block-shiki/highlighter.ts
@@ -13,6 +13,7 @@ import { createJavaScriptRegexEngine } from "shiki/engine/javascript";
export {
codeLanguageOptions,
getCodeLanguageLabel,
+ isMermaidCodeLanguage,
normalizeCodeLanguage,
type CodeLanguageOption,
type SupportedCodeLanguage,
diff --git a/src/features/workspaces/export/workspace-document-pdf-html.test.ts b/src/features/workspaces/export/workspace-document-pdf-html.test.ts
index 34e8b2ee..c26eb347 100644
--- a/src/features/workspaces/export/workspace-document-pdf-html.test.ts
+++ b/src/features/workspaces/export/workspace-document-pdf-html.test.ts
@@ -70,4 +70,25 @@ describe("renderWorkspaceDocumentPdfHtml", () => {
expect(html).toContain("math-fallback");
expect(html).toContain("$\\definitelynotacommand{$");
});
+
+ // A PDF cannot draw the diagram, and its source is authoring material the
+ // reader never asked for, so the block leaves nothing behind.
+ it("drops a mermaid diagram rather than printing its source", async () => {
+ const html = await renderWorkspaceDocumentPdfHtml({
+ type: "doc",
+ content: [
+ {
+ type: "codeBlock",
+ attrs: { language: "mermaid" },
+ content: [{ type: "text", text: "flowchart TD; A[Start] --> B[End]" }],
+ },
+ { type: "paragraph", content: [{ type: "text", text: "Prose survives." }] },
+ ],
+ });
+
+ expect(html).toContain("Prose survives.");
+ expect(html).not.toContain("flowchart");
+ expect(html).not.toContain("Mermaid");
+ expect(html).not.toContain("language-mermaid");
+ });
});
diff --git a/src/features/workspaces/export/workspace-document-pdf-html.ts b/src/features/workspaces/export/workspace-document-pdf-html.ts
index 262387d9..d5360c73 100644
--- a/src/features/workspaces/export/workspace-document-pdf-html.ts
+++ b/src/features/workspaces/export/workspace-document-pdf-html.ts
@@ -5,6 +5,7 @@ import { parseHTML } from "linkedom";
import {
getCodeLanguageLabel,
highlightCodeTokens,
+ isMermaidCodeLanguage,
} from "#/features/workspaces/documents/code-block-shiki/highlighter";
import type { TiptapDocumentJson } from "#/features/workspaces/documents/tiptap-document";
import { getTiptapDocumentSchema } from "#/features/workspaces/documents/tiptap-schema";
@@ -102,10 +103,28 @@ export async function renderWorkspaceDocumentPdfHtml(document: TiptapDocumentJso
return `${article.outerHTML}`;
}
+/**
+ * What a printed page cannot carry. A citation has nothing to link to; a
+ * widget is markup that has to run; a mermaid block is an instruction for
+ * drawing rather than the drawing. Falling back to source for the last two
+ * would put authoring material in front of a reader who asked for a document,
+ * so all three leave nothing behind.
+ */
function removeUnexportedNodes(article: Element) {
for (const node of article.querySelectorAll('citation, [data-type="widget"]')) {
node.remove();
}
+ for (const code of article.querySelectorAll("pre > code")) {
+ if (isMermaidCodeLanguage(readCodeBlockLanguage(code))) {
+ code.parentElement?.remove();
+ }
+ }
+}
+
+/** The language a code block declares, exactly as it was written. */
+function readCodeBlockLanguage(element: Element) {
+ const languageClass = Array.from(element.classList).find((name) => name.startsWith("language-"));
+ return languageClass?.slice("language-".length) || null;
}
function renderMath(article: Element) {
@@ -133,11 +152,8 @@ async function renderCodeBlocks(htmlDocument: Document, article: Element) {
const codeBlocks = Array.from(article.querySelectorAll("pre > code"));
const rendered = await Promise.all(
codeBlocks.map(async (element) => {
- const languageClass = Array.from(element.classList).find((name) =>
- name.startsWith("language-"),
- );
const code = element.textContent ?? "";
- const language = languageClass?.slice("language-".length) || null;
+ const language = readCodeBlockLanguage(element);
return {
code,
element,
diff --git a/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap b/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap
index 916c1cb2..8039e895 100644
--- a/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap
+++ b/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap
@@ -105,7 +105,7 @@ exports[`workspace tool surface > workspace_create_items input schema is stable
"description": "Document to create.",
"properties": {
"initialContent": {
- "description": "Optional initial HTML content. Use semantic HTML with paragraphs, h1-h4, blockquotes, lists, code blocks, horizontal rules, tables, links, and standard text marks. This is HTML, so math is markup rather than delimiters: use or , and keep dollar signs out of the data-latex value. Put every subscript and superscript (exponents like 10^8, indices like x_1) inside math rather than / tags. Chemistry renders with \\ce{...} (e.g. \\ce{CH4 + 2 O2 -> CO2 + 2 H2O}) and quantities with units render with \\pu{...} (e.g. \\pu{9.81 m/s^2}), both inside data-latex. Write literal money as plain text ($30, never \\$30) — a backslash before a dollar sign shows on screen in HTML. For checkboxes, use Item
. Documents cannot hold images: never use ![]()
or , and describe the visual in words instead. Cite workspace sources in documents exactly as in a chat reply, with Item
. Documents cannot hold images: never use ![]()
or — draw a diagram or describe the visual in words instead. Draw a diagram as a mermaid code block: flowchart TD; A[Start] --> B[End]
. It renders as a diagram wherever the item is read or studied, and is left out of a PDF export entirely, so never let a diagram carry a point the surrounding text does not also make. Keep it to about ten nodes with short labels, and include concise accTitle and accDescr lines — they become the diagram's alt text. No frontmatter, init directives, custom styles, HTML, links, or images inside the diagram. Cite workspace sources in documents exactly as in a chat reply, with flowchart TD; A[Start] --> B[End]
. It renders as a diagram wherever the item is read or studied, and is left out of a PDF export entirely, so never let a diagram carry a point the surrounding text does not also make. Keep it to about ten nodes with short labels, and include concise accTitle and accDescr lines — they become the diagram's alt text. No frontmatter, init directives, custom styles, HTML, links, or images inside the diagram. Use item-level relations for sources.",
"items": {
"additionalProperties": false,
"properties": {
@@ -250,7 +250,7 @@ exports[`workspace tool surface > workspace_create_items input schema is stable
"type": "string",
},
"questions": {
- "description": "Ordered multiple-choice questions. Question stems, options, and explanations are HTML. Keep them concise. Use paragraphs, lists, links, code blocks, and standard text marks only. This is HTML, so math is markup rather than delimiters: use or , and keep dollar signs out of the data-latex value. Put every subscript and superscript (exponents like 10^8, indices like x_1) inside math rather than / tags. Chemistry renders with \\ce{...} (e.g. \\ce{CH4 + 2 O2 -> CO2 + 2 H2O}) and quantities with units render with \\pu{...} (e.g. \\pu{9.81 m/s^2}), both inside data-latex. Write literal money as plain text ($30, never \\$30) — a backslash before a dollar sign shows on screen in HTML. Do not use headings, tables, images, widgets, task lists, or citations inside a question. Use item-level relations for sources. Write correctAnswer as its own field and never hint at it in the stem or option order: the server shuffles the options and records which one is correct. Every distractor must be strictly wrong yet plausible, reflect a specific misconception, and match the correct answer's length and tone. Prefer 3 distractors; use 1 for true/false. Questions should test understanding from the source material, not trivia recall.",
+ "description": "Ordered multiple-choice questions. Question stems, options, and explanations are HTML. Keep them concise. Use paragraphs, lists, links, code blocks, and standard text marks only. This is HTML, so math is markup rather than delimiters: use or , and keep dollar signs out of the data-latex value. Put every subscript and superscript (exponents like 10^8, indices like x_1) inside math rather than / tags. Chemistry renders with \\ce{...} (e.g. \\ce{CH4 + 2 O2 -> CO2 + 2 H2O}) and quantities with units render with \\pu{...} (e.g. \\pu{9.81 m/s^2}), both inside data-latex. Write literal money as plain text ($30, never \\$30) — a backslash before a dollar sign shows on screen in HTML. Do not use headings, tables, images, widgets, task lists, or citations inside a question. Draw a diagram as a mermaid code block: flowchart TD; A[Start] --> B[End]
. It renders as a diagram wherever the item is read or studied, and is left out of a PDF export entirely, so never let a diagram carry a point the surrounding text does not also make. Keep it to about ten nodes with short labels, and include concise accTitle and accDescr lines — they become the diagram's alt text. No frontmatter, init directives, custom styles, HTML, links, or images inside the diagram. A diagram usually belongs in the stem or the explanation; if one option needs it, give them all one, since an option taller than the rest hints at the answer. Use item-level relations for sources. Write correctAnswer as its own field and never hint at it in the stem or option order: the server shuffles the options and records which one is correct. Every distractor must be strictly wrong yet plausible, reflect a specific misconception, and match the correct answer's length and tone. Prefer 3 distractors; use 1 for true/false. Questions should test understanding from the source material, not trivia recall.",
"items": {
"additionalProperties": false,
"properties": {
@@ -387,7 +387,7 @@ exports[`workspace tool surface > workspace_edit_item input schema is stable 1`]
"description": "Document edits.",
"properties": {
"edits": {
- "description": "Ordered document edits using exact refs from a read. Available operations: insert_before, insert_after, update, replace, replace_text, move, and delete. update accepts exactly one top-level block; replace may replace one block with several. move requires exactly one of beforeRef or afterRef. Use semantic HTML with paragraphs, h1-h4, blockquotes, lists, code blocks, horizontal rules, tables, links, and standard text marks. This is HTML, so math is markup rather than delimiters: use or , and keep dollar signs out of the data-latex value. Put every subscript and superscript (exponents like 10^8, indices like x_1) inside math rather than / tags. Chemistry renders with \\ce{...} (e.g. \\ce{CH4 + 2 O2 -> CO2 + 2 H2O}) and quantities with units render with \\pu{...} (e.g. \\pu{9.81 m/s^2}), both inside data-latex. Write literal money as plain text ($30, never \\$30) — a backslash before a dollar sign shows on screen in HTML. For checkboxes, use Item
. Documents cannot hold images: never use ![]()
or , and describe the visual in words instead. Cite workspace sources in documents exactly as in a chat reply, with Item
. Documents cannot hold images: never use ![]()
or — draw a diagram or describe the visual in words instead. Draw a diagram as a mermaid code block: flowchart TD; A[Start] --> B[End]
. It renders as a diagram wherever the item is read or studied, and is left out of a PDF export entirely, so never let a diagram carry a point the surrounding text does not also make. Keep it to about ten nodes with short labels, and include concise accTitle and accDescr lines — they become the diagram's alt text. No frontmatter, init directives, custom styles, HTML, links, or images inside the diagram. Cite workspace sources in documents exactly as in a chat reply, with flowchart TD; A[Start] --> B[End]
. It renders as a diagram wherever the item is read or studied, and is left out of a PDF export entirely, so never let a diagram carry a point the surrounding text does not also make. Keep it to about ten nodes with short labels, and include concise accTitle and accDescr lines — they become the diagram's alt text. No frontmatter, init directives, custom styles, HTML, links, or images inside the diagram. Use item-level relations for sources.",
"items": {
"anyOf": [
{
@@ -733,7 +733,7 @@ exports[`workspace tool surface > workspace_edit_item input schema is stable 1`]
"description": "Quiz edits.",
"properties": {
"edits": {
- "description": "Ordered quiz edits using exact refs from a read. Available operations: insert_before, insert_after, update, replace, replace_text, move, and delete. insert and replace take a full authored question and reshuffle its options; update changes only the stem or explanation in place; replace_text requires question, options, or explanation as field and never reshuffles; move requires exactly one of beforeRef or afterRef. Question stems, options, and explanations are HTML. Keep them concise. Use paragraphs, lists, links, code blocks, and standard text marks only. This is HTML, so math is markup rather than delimiters: use or , and keep dollar signs out of the data-latex value. Put every subscript and superscript (exponents like 10^8, indices like x_1) inside math rather than / tags. Chemistry renders with \\ce{...} (e.g. \\ce{CH4 + 2 O2 -> CO2 + 2 H2O}) and quantities with units render with \\pu{...} (e.g. \\pu{9.81 m/s^2}), both inside data-latex. Write literal money as plain text ($30, never \\$30) — a backslash before a dollar sign shows on screen in HTML. Do not use headings, tables, images, widgets, task lists, or citations inside a question. Use item-level relations for sources. Write correctAnswer as its own field and never hint at it in the stem or option order: the server shuffles the options and records which one is correct. Every distractor must be strictly wrong yet plausible, reflect a specific misconception, and match the correct answer's length and tone. Prefer 3 distractors; use 1 for true/false. Questions should test understanding from the source material, not trivia recall.",
+ "description": "Ordered quiz edits using exact refs from a read. Available operations: insert_before, insert_after, update, replace, replace_text, move, and delete. insert and replace take a full authored question and reshuffle its options; update changes only the stem or explanation in place; replace_text requires question, options, or explanation as field and never reshuffles; move requires exactly one of beforeRef or afterRef. Question stems, options, and explanations are HTML. Keep them concise. Use paragraphs, lists, links, code blocks, and standard text marks only. This is HTML, so math is markup rather than delimiters: use or , and keep dollar signs out of the data-latex value. Put every subscript and superscript (exponents like 10^8, indices like x_1) inside math rather than / tags. Chemistry renders with \\ce{...} (e.g. \\ce{CH4 + 2 O2 -> CO2 + 2 H2O}) and quantities with units render with \\pu{...} (e.g. \\pu{9.81 m/s^2}), both inside data-latex. Write literal money as plain text ($30, never \\$30) — a backslash before a dollar sign shows on screen in HTML. Do not use headings, tables, images, widgets, task lists, or citations inside a question. Draw a diagram as a mermaid code block: flowchart TD; A[Start] --> B[End]
. It renders as a diagram wherever the item is read or studied, and is left out of a PDF export entirely, so never let a diagram carry a point the surrounding text does not also make. Keep it to about ten nodes with short labels, and include concise accTitle and accDescr lines — they become the diagram's alt text. No frontmatter, init directives, custom styles, HTML, links, or images inside the diagram. A diagram usually belongs in the stem or the explanation; if one option needs it, give them all one, since an option taller than the rest hints at the answer. Use item-level relations for sources. Write correctAnswer as its own field and never hint at it in the stem or option order: the server shuffles the options and records which one is correct. Every distractor must be strictly wrong yet plausible, reflect a specific misconception, and match the correct answer's length and tone. Prefer 3 distractors; use 1 for true/false. Questions should test understanding from the source material, not trivia recall.",
"items": {
"anyOf": [
{
diff --git a/src/features/workspaces/operations/workspace-tool-schemas.ts b/src/features/workspaces/operations/workspace-tool-schemas.ts
index 249a88d6..d36db2e8 100644
--- a/src/features/workspaces/operations/workspace-tool-schemas.ts
+++ b/src/features/workspaces/operations/workspace-tool-schemas.ts
@@ -36,17 +36,25 @@ export { workspaceReadItemsInputSchema, workspaceReadItemsOutputSchema };
const workspaceHtmlMathInstruction =
'This is HTML, so math is markup rather than delimiters: use or , and keep dollar signs out of the data-latex value. Put every subscript and superscript (exponents like 10^8, indices like x_1) inside math rather than / tags. Chemistry renders with \\ce{...} (e.g. \\ce{CH4 + 2 O2 -> CO2 + 2 H2O}) and quantities with units render with \\pu{...} (e.g. \\pu{9.81 m/s^2}), both inside data-latex. Write literal money as plain text ($30, never \\$30) — a backslash before a dollar sign shows on screen in HTML.';
+/**
+ * The one diagram route every HTML surface shares. A mermaid block is an
+ * ordinary code block, so cards and questions get diagrams without opening
+ * their allowlist to widgets — which stay documents-only.
+ */
+const workspaceHtmlDiagramInstruction =
+ 'Draw a diagram as a mermaid code block: flowchart TD; A[Start] --> B[End]
. It renders as a diagram wherever the item is read or studied, and is left out of a PDF export entirely, so never let a diagram carry a point the surrounding text does not also make. Keep it to about ten nodes with short labels, and include concise accTitle and accDescr lines — they become the diagram\'s alt text. No frontmatter, init directives, custom styles, HTML, links, or images inside the diagram.';
+
/**
* Keep discovery and serialization beside the document tool. The activated
* skill owns the authoring contract so the two prompts cannot drift apart.
*/
const workspaceWidgetHtmlInstruction = `A widget is one interactive block inside a document. Use one when the user explicitly asks for a widget, asks for interaction or live computation, or wants a document visual that ordinary blocks cannot express. Keep ordinary content in ordinary blocks. Before authoring or editing widget source, activate the "widget-authoring" skill and follow its HTML, sandbox, layout, and editing contract. Serialize the result as …HTML-escaped fragment….`;
-export const workspaceDocumentHtmlInstruction = `Use semantic HTML with paragraphs, h1-h4, blockquotes, lists, code blocks, horizontal rules, tables, links, and standard text marks. ${workspaceHtmlMathInstruction} For checkboxes, use Item
. Documents cannot hold images: never use ![]()
or , and describe the visual in words instead. Cite workspace sources in documents exactly as in a chat reply, with Item
. Documents cannot hold images: never use ![]()
or — draw a diagram or describe the visual in words instead. ${workspaceHtmlDiagramInstruction} Cite workspace sources in documents exactly as in a chat reply, with
{
diff --git a/src/features/workspaces/components/quizzes/QuizViewer.tsx b/src/features/workspaces/components/quizzes/QuizViewer.tsx
index 74054ef8..3ac924e8 100644
--- a/src/features/workspaces/components/quizzes/QuizViewer.tsx
+++ b/src/features/workspaces/components/quizzes/QuizViewer.tsx
@@ -10,6 +10,7 @@ import { StudyRichText } from "#/features/workspaces/components/study/StudyRichT
import {
StudyAiActionButton,
StudyNavButton,
+ useStudySessionFocus,
} from "#/features/workspaces/components/study/StudySessionControls";
import { StudyToolbar } from "#/features/workspaces/components/study/StudyToolbar";
import { useWorkspaceItemToolbar } from "#/features/workspaces/components/WorkspaceItemToolbarSlot";
@@ -119,6 +120,7 @@ function QuizStudySession({
? questions.findIndex((question) => question.id === currentQuestion.id) + 1
: 0;
const answer = currentQuestion ? getQuizAnswer(currentQuestion, studyState) : undefined;
+ const sectionRef = useStudySessionFocus(currentQuestion?.id);
const quizProgress = useMemo(
() => summarizeQuizStudyProgress(questions, studyState),
[questions, studyState],
@@ -299,6 +301,7 @@ function QuizStudySession({
return (
— out of reach of the section's
+ * keydown handler. Attach the returned ref to the section; when an entry change
+ * strands focus on , the section takes it back.
+ */
+export function useStudySessionFocus(entryKey: string | undefined) {
+ const sectionRef = useRef(null);
+ const previousKey = useRef(entryKey);
+ useEffect(() => {
+ if (previousKey.current === entryKey) return;
+ previousKey.current = entryKey;
+ if (document.activeElement === document.body) sectionRef.current?.focus();
+ }, [entryKey]);
+ return sectionRef;
+}
+
/**
* Asks the AI for help with the item on screen — a hint before answering, a
* fuller explanation after. Amber everywhere so "ask AI" reads the same in
From 2aa4b94454afd5f6225caac61c3dd75e3834593a Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Sat, 15 Aug 2026 15:28:43 -0400
Subject: [PATCH 12/14] fix(workspaces): show a static language label in
read-only code blocks
The node view assumed its host was the editable document editor; study
viewers now render it read-only, where the language dropdown is editing
chrome with nothing to edit.
---
.../code-block-shiki/CodeBlockNodeView.tsx | 56 ++++++++++---------
1 file changed, 31 insertions(+), 25 deletions(-)
diff --git a/src/features/workspaces/documents/code-block-shiki/CodeBlockNodeView.tsx b/src/features/workspaces/documents/code-block-shiki/CodeBlockNodeView.tsx
index cb7dac2c..07b7215d 100644
--- a/src/features/workspaces/documents/code-block-shiki/CodeBlockNodeView.tsx
+++ b/src/features/workspaces/documents/code-block-shiki/CodeBlockNodeView.tsx
@@ -71,32 +71,38 @@ export function CodeBlockNodeView({
>
- {
- updateAttributes({
- language: value === "plain" ? null : (value as SupportedCodeLanguage),
- });
- }}
- >
-
-
- {(value: string | null) =>
- value === "plain" ? "Plain text" : getCodeLanguageLabel(value)
- }
-
-
-
-
- Plain text
-
- {codeLanguageOptions.map((option) => (
-
- {option.label}
+ {/* Study viewers render this node view read-only, where the
+ language is a fact to show, not a setting to change. */}
+ {editor.isEditable ? (
+ {
+ updateAttributes({
+ language: value === "plain" ? null : (value as SupportedCodeLanguage),
+ });
+ }}
+ >
+
+
+ {(value: string | null) =>
+ value === "plain" ? "Plain text" : getCodeLanguageLabel(value)
+ }
+
+
+
+
+ Plain text
- ))}
-
-
+ {codeLanguageOptions.map((option) => (
+
+ {option.label}
+
+ ))}
+
+
+ ) : (
+ getCodeLanguageLabel(language)
+ )}
();
for (const ref of new Set(refs)) {
const address = parseWorkspaceAddress(ref);
if (!address) continue;
- const resolved = await getWorkspaceItemByRefKey({
- refKey: address.refKey,
- workspaceId: input.context.workspaceId,
- });
+ const resolved = refKeyIndex.get(address.refKey);
const location = resolved ? resolveWorkspaceAddressLocation(resolved.item, address) : undefined;
if (location) locations.set(ref, location);
}
diff --git a/src/features/workspaces/operations/read-items.ts b/src/features/workspaces/operations/read-items.ts
index 8f4ba239..9e1a9214 100644
--- a/src/features/workspaces/operations/read-items.ts
+++ b/src/features/workspaces/operations/read-items.ts
@@ -9,7 +9,7 @@ import { recordWorkspaceFileReadOutcomes } from "#/features/workspaces/content/w
import { getDocumentSessionFromEnv } from "#/features/workspaces/document-session-access";
import { readFlashcardViewer } from "#/features/workspaces/flashcards/flashcard-study-persistence";
import { readQuizViewer } from "#/features/workspaces/quizzes/quiz-study-persistence";
-import { getWorkspaceItemByRefKey } from "#/features/workspaces/persistence/workspace-items";
+import { getWorkspaceItemRefKeyIndex } from "#/features/workspaces/persistence/workspace-items";
import type { WorkspaceAccessContext } from "#/features/workspaces/operations/workspace-access-context";
import { authorizeWorkspaceOperation } from "#/features/workspaces/operations/workspace-operation-context";
@@ -25,6 +25,8 @@ export async function readWorkspaceItemsOperation(
access: "read",
context: accessContext,
});
+ // Lazy so path-only batches skip it; shared so N ref requests cost one page read.
+ let refKeyIndex: ReturnType | undefined;
const results = await readWorkspaceContent({
bucket: env.WORKSPACE_FILES,
getDocumentSession: (itemId) =>
@@ -44,8 +46,10 @@ export async function readWorkspaceItemsOperation(
userId: accessContext.actor.userId,
workspaceId: accessContext.workspaceId,
}),
- resolveRefKey: (refKey) =>
- getWorkspaceItemByRefKey({ refKey, workspaceId: accessContext.workspaceId }),
+ resolveRefKey: async (refKey) => {
+ refKeyIndex ??= getWorkspaceItemRefKeyIndex({ workspaceId: accessContext.workspaceId });
+ return (await refKeyIndex).get(refKey);
+ },
requests: input.requests,
workspaceId: accessContext.workspaceId,
});
diff --git a/src/features/workspaces/persistence/workspace-items.ts b/src/features/workspaces/persistence/workspace-items.ts
index 49ee9328..32fd245c 100644
--- a/src/features/workspaces/persistence/workspace-items.ts
+++ b/src/features/workspaces/persistence/workspace-items.ts
@@ -124,13 +124,20 @@ export async function getWorkspaceItemPaths(input: WorkspaceScoped) {
+/**
+ * Resolves item address refKeys to live items and their paths. Costs one
+ * workspace page read however many refKeys the caller then looks up, so
+ * callers with several refs to resolve share a single index.
+ */
+export async function getWorkspaceItemRefKeyIndex(input: WorkspaceScoped