@deskwork/core 0.14.0 → 0.15.0

package/dist/entry/create.d.ts

@@ -0,0 +1,56 @@
+import type { Entry, ReviewState, Stage } from '../schema/entry.ts';
+/**
+ * Inputs for a freshly-minted entry sidecar.
+ *
+ * Both `deskwork add` and `deskwork ingest --apply` produce new entries
+ * that need a sidecar written under the Phase 30 contract. They differ
+ * in the optional fields (ingest knows an `artifactPath`; published
+ * candidates carry a `datePublishedDate`; legacy `Review` mapping
+ * produces a `reviewState`), but the required-field shape and the
+ * defaults (`keywords=[]`, `iterationByStage={}`, `createdAt=updatedAt=now`)
+ * are identical. This helper is the single point that knows the new-entry
+ * shape so both call sites stay aligned.
+ */
+export interface CreateEntryParams {
+    readonly uuid: string;
+    readonly slug: string;
+    readonly title: string;
+    readonly description?: string;
+    readonly currentStage: Stage;
+    readonly source: string;
+    readonly reviewState?: ReviewState;
+    readonly artifactPath?: string;
+    /**
+     * YYYY-MM-DD; the helper converts to a full ISO datetime so the
+     * `Entry.datePublished` schema (`z.string().datetime()`) accepts it.
+     * Only honored when `currentStage === 'Published'`.
+     */
+    readonly datePublishedDate?: string;
+    readonly keywords?: readonly string[];
+    /**
+     * Test seam — defaults to `new Date()` when omitted. Lets unit tests
+     * pin `createdAt`/`updatedAt`/`datePublished`-derived ISO without
+     * stubbing globals.
+     */
+    readonly now?: Date;
+}
+/**
+ * Build a fresh `Entry` from the supplied params, write it to
+ * `.deskwork/entries/<uuid>.json`, and return the constructed Entry
+ * (callers don't need the return value but it's cheap to provide and
+ * useful in tests).
+ *
+ * Defaults:
+ *   - `keywords` → `[]`
+ *   - `iterationByStage` → `{}`
+ *   - `createdAt` / `updatedAt` → `now.toISOString()`
+ *   - `datePublished` (only if `currentStage === 'Published'` and
+ *     `datePublishedDate` is supplied) → `${datePublishedDate}T00:00:00.000Z`
+ *
+ * Phase 30 contract: every UUID in `calendar.md` must have a sidecar.
+ * Both `deskwork add` and `deskwork ingest --apply` MUST pair their
+ * calendar.md write with a `createFreshEntrySidecar` call to satisfy
+ * doctor's `calendar-sidecar` validator.
+ */
+export declare function createFreshEntrySidecar(projectRoot: string, params: CreateEntryParams): Promise<Entry>;
+//# sourceMappingURL=create.d.ts.map

package/dist/entry/create.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/entry/create.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAEpE;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,KAAK,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,uBAAuB,CAC3C,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,iBAAiB,GACxB,OAAO,CAAC,KAAK,CAAC,CAqBhB"}

package/dist/entry/create.js

@@ -0,0 +1,42 @@
+import { writeSidecar } from "../sidecar/write.js";
+/**
+ * Build a fresh `Entry` from the supplied params, write it to
+ * `.deskwork/entries/<uuid>.json`, and return the constructed Entry
+ * (callers don't need the return value but it's cheap to provide and
+ * useful in tests).
+ *
+ * Defaults:
+ *   - `keywords` → `[]`
+ *   - `iterationByStage` → `{}`
+ *   - `createdAt` / `updatedAt` → `now.toISOString()`
+ *   - `datePublished` (only if `currentStage === 'Published'` and
+ *     `datePublishedDate` is supplied) → `${datePublishedDate}T00:00:00.000Z`
+ *
+ * Phase 30 contract: every UUID in `calendar.md` must have a sidecar.
+ * Both `deskwork add` and `deskwork ingest --apply` MUST pair their
+ * calendar.md write with a `createFreshEntrySidecar` call to satisfy
+ * doctor's `calendar-sidecar` validator.
+ */
+export async function createFreshEntrySidecar(projectRoot, params) {
+    const at = (params.now ?? new Date()).toISOString();
+    const entry = {
+        uuid: params.uuid,
+        slug: params.slug,
+        title: params.title,
+        ...(params.description ? { description: params.description } : {}),
+        keywords: params.keywords ? [...params.keywords] : [],
+        source: params.source,
+        currentStage: params.currentStage,
+        iterationByStage: {},
+        ...(params.reviewState !== undefined ? { reviewState: params.reviewState } : {}),
+        ...(params.artifactPath !== undefined ? { artifactPath: params.artifactPath } : {}),
+        ...(params.currentStage === 'Published' && params.datePublishedDate
+            ? { datePublished: `${params.datePublishedDate}T00:00:00.000Z` }
+            : {}),
+        createdAt: at,
+        updatedAt: at,
+    };
+    await writeSidecar(projectRoot, entry);
+    return entry;
+}
+//# sourceMappingURL=create.js.map

package/dist/entry/create.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.js","sourceRoot":"","sources":["../../src/entry/create.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAuCnD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,WAAmB,EACnB,MAAyB;IAEzB,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IACpD,MAAM,KAAK,GAAU;QACnB,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClE,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE;QACrD,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,gBAAgB,EAAE,EAAE;QACpB,GAAG,CAAC,MAAM,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChF,GAAG,CAAC,MAAM,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnF,GAAG,CAAC,MAAM,CAAC,YAAY,KAAK,WAAW,IAAI,MAAM,CAAC,iBAAiB;YACjE,CAAC,CAAC,EAAE,aAAa,EAAE,GAAG,MAAM,CAAC,iBAAiB,gBAAgB,EAAE;YAChE,CAAC,CAAC,EAAE,CAAC;QACP,SAAS,EAAE,EAAE;QACb,SAAS,EAAE,EAAE;KACd,CAAC;IACF,MAAM,YAAY,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;IACvC,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/iterate/iterate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"iterate.d.ts","sourceRoot":"","sources":["../../src/iterate/iterate.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAS,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAEvD,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;CAEd;AAED,UAAU,aAAa;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,WAAW,CAAC;CAC1B;AAaD,wBAAsB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAiFpG"}
+{"version":3,"file":"iterate.d.ts","sourceRoot":"","sources":["../../src/iterate/iterate.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAS,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAEvD,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;CAEd;AAED,UAAU,aAAa;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,WAAW,CAAC;CAC1B;AAaD,wBAAsB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CA8EpG"}

package/dist/iterate/iterate.js

@@ -3,7 +3,6 @@ import { join } from 'node:path';
 import { readSidecar } from "../sidecar/read.js";
 import { writeSidecar } from "../sidecar/write.js";
 import { appendJournalEvent } from "../journal/append.js";
-import { readJournalEvents } from "../journal/read.js";
 import { getContentDir } from "../config.js";
 const STAGE_ARTIFACT_PATH = {
     Ideas: (slug, contentDir) => join(contentDir, slug, 'scrapbook', 'idea.md'),
@@ -38,17 +37,16 @@ export async function iterateEntry(projectRoot, opts) {
         artifactPath = pathFn(sidecar.slug, contentDir);
     }
     const markdown = await readFile(artifactPath, 'utf8');
-    // Guard: refuse to iterate when on-disk content matches the most recent
-    // iteration journal entry for this stage. Prevents no-op revision bumps
-    // (the operator forgot to actually edit the file).
-    const events = await readJournalEvents(projectRoot, { entryId: sidecar.uuid });
-    const lastIteration = events
-        .filter((e) => e.kind === 'iteration' && e.stage === sidecar.currentStage)
-        .at(-1);
-    if (lastIteration && lastIteration.kind === 'iteration' && lastIteration.markdown === markdown) {
-        throw new Error(`Cannot iterate: ${artifactPath} content is unchanged since iteration v${lastIteration.version}. ` +
-            'Edit the file before iterating.');
-    }
+    // Iteration is the operator's explicit "pin a new version" decision;
+    // the core helper records what was asked, not what the helper thinks
+    // counts as "real change." A real iteration can be motivated by
+    // marginalia, scrapbook additions, decisions captured outside the
+    // file body, or any reason the operator hasn't communicated to the
+    // system. Gating on a content-diff check earlier here put a hard
+    // error in front of the operator's review-surface Iterate button
+    // when they had added marginalia but not edited the file body.
+    // Removed (#188-followup): the orchestrating skill (`/deskwork:iterate`)
+    // is the right place to decide whether the file needs editing first.
     const priorVersion = sidecar.iterationByStage[sidecar.currentStage] ?? 0;
     const newVersion = priorVersion + 1;
     const at = new Date().toISOString();

package/dist/iterate/iterate.js.map

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

package/dist/rehype-rewrite-scrapbook-images.mjs

@@ -0,0 +1,78 @@
+/**
+ * Rewrite relative `<img src>` paths that point into the entry's
+ * scrapbook so the studio's review surface can serve them via the
+ * scrapbook-file route.
+ *
+ * Why this exists: an audit doc / draft / spec authored alongside a
+ * `scrapbook/` directory will reference its assets with relative URLs
+ * like `![alt](./scrapbook/figure-1.png)` or `![alt](scrapbook/figure-1.png)`.
+ * Those relative URLs render correctly in any normal markdown viewer
+ * (GitHub, VS Code, IDE preview) because the renderer resolves them
+ * against the file's location on disk. On the studio's review surface
+ * the page URL is `/dev/editorial-review/entry/<uuid>`, so the same
+ * relative URL would resolve to a path the studio doesn't serve. This
+ * plugin rewrites those `<img src>` values to the absolute scrapbook-file
+ * route URL, which the studio DOES serve.
+ *
+ * The markdown source stays portable. The plugin only fires when the
+ * renderer is given `{ entryId, site }` options (i.e. the studio's
+ * review surface). Other call sites (e.g. published-site rendering)
+ * leave the relative URLs alone.
+ *
+ * @typedef {object} Options
+ * @property {string} entryId  Entry UUID. Required.
+ * @property {string} site     Site/collection slug. Required.
+ *
+ * @param {Options} options
+ * @returns {(tree: any) => void}
+ */
+export default function rehypeRewriteScrapbookImages(options) {
+  const { entryId, site } = options || {};
+  if (!entryId || !site) {
+    throw new Error(
+      'rehypeRewriteScrapbookImages: { entryId, site } are required',
+    );
+  }
+
+  const baseUrl =
+    `/api/dev/scrapbook-file` +
+    `?site=${encodeURIComponent(site)}` +
+    `&entryId=${encodeURIComponent(entryId)}`;
+
+  /** @param {string} src */
+  function rewrite(src) {
+    // Match leading `./scrapbook/<filename>` or `scrapbook/<filename>`.
+    // Don't rewrite absolute URLs (`http://`, `https://`, `/api/...`),
+    // anchor links (`#...`), data URIs (`data:...`), or paths into a
+    // sibling directory other than scrapbook.
+    const m = src.match(/^(?:\.\/)?scrapbook\/([^/?#]+)$/);
+    if (!m) return null;
+    const filename = m[1];
+    return `${baseUrl}&name=${encodeURIComponent(filename)}`;
+  }
+
+  return function transformer(tree) {
+    visit(tree, 'element', (node) => {
+      if (!node || node.tagName !== 'img') return;
+      if (!node.properties || typeof node.properties.src !== 'string') return;
+      const newSrc = rewrite(node.properties.src);
+      if (newSrc) node.properties.src = newSrc;
+    });
+  };
+}
+
+/**
+ * Minimal hast visitor — walks every node depth-first, calls visitor
+ * for nodes whose `type` matches.
+ *
+ * @param {any} tree
+ * @param {string} typeFilter
+ * @param {(node: any) => void} fn
+ */
+function visit(tree, typeFilter, fn) {
+  if (!tree) return;
+  if (tree.type === typeFilter) fn(tree);
+  if (Array.isArray(tree.children)) {
+    for (const child of tree.children) visit(child, typeFilter, fn);
+  }
+}

package/dist/review/render.d.ts

@@ -14,6 +14,16 @@
  * the review surface needs the outline visible for annotate-and-iterate
  * work.
  */
+/** Optional rendering context. When the renderer is invoked from a
+ *  surface that has an entry binding (e.g. the studio's review surface),
+ *  pass `{ entryId, site }` to enable rewriting of relative
+ *  `./scrapbook/<file>` image URLs to the absolute scrapbook-file route
+ *  URL the studio serves. Other surfaces leave relative URLs alone so
+ *  the markdown source stays portable across renderers. */
+export interface RenderOptions {
+    readonly entryId?: string;
+    readonly site?: string;
+}
 export interface ParsedDraft {
     /** Frontmatter values. Values are whatever YAML parses them to. */
     frontmatter: Record<string, unknown>;
@@ -23,5 +33,5 @@ export interface ParsedDraft {
 /** Split a draft into its frontmatter and body. */
 export declare function parseDraftFrontmatter(markdown: string): ParsedDraft;
 /** Render a markdown string as HTML. */
-export declare function renderMarkdownToHtml(markdown: string): Promise<string>;
+export declare function renderMarkdownToHtml(markdown: string, options?: RenderOptions): Promise<string>;
 //# sourceMappingURL=render.d.ts.map

package/dist/review/render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/review/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAYH,MAAM,WAAW,WAAW;IAC1B,mEAAmE;IACnE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,mDAAmD;AACnD,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAGnE;AAED,wCAAwC;AACxC,wBAAsB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAS5E"}
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/review/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAeH;;;;;2DAK2D;AAC3D,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,mEAAmE;IACnE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,mDAAmD;AACnD,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAGnE;AAED,wCAAwC;AACxC,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,MAAM,CAAC,CA6BjB"}

package/dist/review/render.js

@@ -16,6 +16,7 @@
  */
 import { unified } from 'unified';
 import remarkParse from 'remark-parse';
+import remarkGfm from 'remark-gfm';
 import remarkRehype from 'remark-rehype';
 import rehypeStringify from 'rehype-stringify';
 import { parseFrontmatter } from "../frontmatter.js";
@@ -23,20 +24,41 @@ import { parseFrontmatter } from "../frontmatter.js";
 import remarkImageFigure from '../remark-image-figure.mjs';
 // @ts-expect-error — JS module without a .d.ts; the plugin is plain mdast traversal.
 import remarkStripFirstH1 from '../remark-strip-first-h1.mjs';
+// @ts-expect-error — JS module without a .d.ts; the plugin is a plain hast visitor.
+import rehypeRewriteScrapbookImages from '../rehype-rewrite-scrapbook-images.mjs';
 /** Split a draft into its frontmatter and body. */
 export function parseDraftFrontmatter(markdown) {
     const { data, body } = parseFrontmatter(markdown);
     return { frontmatter: data, body };
 }
 /** Render a markdown string as HTML. */
-export async function renderMarkdownToHtml(markdown) {
-    const result = await unified()
+export async function renderMarkdownToHtml(markdown, options = {}) {
+    // remark-gfm adds GitHub Flavored Markdown — tables, strikethrough,
+    // task lists, footnotes, autolinks. Operator-authored content
+    // routinely uses tables (audit docs, comparison matrices); without
+    // gfm those rendered as raw `| col | col |` text on the review
+    // surface.
+    // Studio-surface scrapbook URL rewrite — only fires when both
+    // `entryId` and `site` are provided. The markdown source is expected
+    // to use portable relative URLs like `./scrapbook/<file>`; the
+    // rewrite produces the absolute scrapbook-file route URL that the
+    // studio serves at runtime. Other call sites (published-site
+    // rendering, tests with no entry binding) leave the relative URLs
+    // alone so the markdown stays renderable in GitHub / VS Code / any
+    // other markdown viewer.
+    const studioRewrite = options.entryId && options.site
+        ? { entryId: options.entryId, site: options.site }
+        : null;
+    const base = unified()
         .use(remarkParse)
+        .use(remarkGfm)
         .use(remarkStripFirstH1)
         .use(remarkImageFigure)
-        .use(remarkRehype)
-        .use(rehypeStringify)
-        .process(markdown);
+        .use(remarkRehype);
+    const withRewrite = studioRewrite
+        ? base.use(rehypeRewriteScrapbookImages, studioRewrite)
+        : base;
+    const result = await withRewrite.use(rehypeStringify).process(markdown);
     return String(result);
 }
 //# sourceMappingURL=render.js.map

package/dist/review/render.js.map

@@ -1 +1 @@
-{"version":3,"file":"render.js","sourceRoot":"","sources":["../../src/review/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,WAAW,MAAM,cAAc,CAAC;AACvC,OAAO,YAAY,MAAM,eAAe,CAAC;AACzC,OAAO,eAAe,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,qFAAqF;AACrF,OAAO,iBAAiB,MAAM,4BAA4B,CAAC;AAC3D,qFAAqF;AACrF,OAAO,kBAAkB,MAAM,8BAA8B,CAAC;AAS9D,mDAAmD;AACnD,MAAM,UAAU,qBAAqB,CAAC,QAAgB;IACpD,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAClD,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACrC,CAAC;AAED,wCAAwC;AACxC,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,QAAgB;IACzD,MAAM,MAAM,GAAG,MAAM,OAAO,EAAE;SAC3B,GAAG,CAAC,WAAW,CAAC;SAChB,GAAG,CAAC,kBAAkB,CAAC;SACvB,GAAG,CAAC,iBAAiB,CAAC;SACtB,GAAG,CAAC,YAAY,CAAC;SACjB,GAAG,CAAC,eAAe,CAAC;SACpB,OAAO,CAAC,QAAQ,CAAC,CAAC;IACrB,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC;AACxB,CAAC"}
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../../src/review/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,WAAW,MAAM,cAAc,CAAC;AACvC,OAAO,SAAS,MAAM,YAAY,CAAC;AACnC,OAAO,YAAY,MAAM,eAAe,CAAC;AACzC,OAAO,eAAe,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,qFAAqF;AACrF,OAAO,iBAAiB,MAAM,4BAA4B,CAAC;AAC3D,qFAAqF;AACrF,OAAO,kBAAkB,MAAM,8BAA8B,CAAC;AAC9D,oFAAoF;AACpF,OAAO,4BAA4B,MAAM,wCAAwC,CAAC;AAoBlF,mDAAmD;AACnD,MAAM,UAAU,qBAAqB,CAAC,QAAgB;IACpD,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAClD,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACrC,CAAC;AAED,wCAAwC;AACxC,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,QAAgB,EAChB,UAAyB,EAAE;IAE3B,oEAAoE;IACpE,8DAA8D;IAC9D,mEAAmE;IACnE,+DAA+D;IAC/D,WAAW;IACX,8DAA8D;IAC9D,qEAAqE;IACrE,+DAA+D;IAC/D,kEAAkE;IAClE,6DAA6D;IAC7D,kEAAkE;IAClE,mEAAmE;IACnE,yBAAyB;IACzB,MAAM,aAAa,GACjB,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,IAAI;QAC7B,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE;QAClD,CAAC,CAAC,IAAI,CAAC;IACX,MAAM,IAAI,GAAG,OAAO,EAAE;SACnB,GAAG,CAAC,WAAW,CAAC;SAChB,GAAG,CAAC,SAAS,CAAC;SACd,GAAG,CAAC,kBAAkB,CAAC;SACvB,GAAG,CAAC,iBAAiB,CAAC;SACtB,GAAG,CAAC,YAAY,CAAC,CAAC;IACrB,MAAM,WAAW,GAAG,aAAa;QAC/B,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,4BAA4B,EAAE,aAAa,CAAC;QACvD,CAAC,CAAC,IAAI,CAAC;IACT,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACxE,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC;AACxB,CAAC"}

package/dist/schema/draft-annotation.d.ts

@@ -31,31 +31,31 @@ export declare const DraftAnnotationSchema: z.ZodDiscriminatedUnion<"type", [z.Z
     workflowId: z.ZodString;
     id: z.ZodString;
 }, "strip", z.ZodTypeAny, {
+    id: string;
     type: "comment";
     version: number;
+    createdAt: string;
+    workflowId: string;
     range: {
         start: number;
         end: number;
     };
     text: string;
-    createdAt: string;
-    workflowId: string;
-    id: string;
-    category?: "voice-drift" | "missing-receipt" | "tutorial-framing" | "saas-vocabulary" | "fake-authority" | "structural" | "other" | undefined;
     anchor?: string | undefined;
+    category?: "other" | "voice-drift" | "missing-receipt" | "tutorial-framing" | "saas-vocabulary" | "fake-authority" | "structural" | undefined;
 }, {
+    id: string;
     type: "comment";
     version: number;
+    createdAt: string;
+    workflowId: string;
     range: {
         start: number;
         end: number;
     };
     text: string;
-    createdAt: string;
-    workflowId: string;
-    id: string;
-    category?: "voice-drift" | "missing-receipt" | "tutorial-framing" | "saas-vocabulary" | "fake-authority" | "structural" | "other" | undefined;
     anchor?: string | undefined;
+    category?: "other" | "voice-drift" | "missing-receipt" | "tutorial-framing" | "saas-vocabulary" | "fake-authority" | "structural" | undefined;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"edit">;
     beforeVersion: z.ZodNumber;
@@ -65,18 +65,18 @@ export declare const DraftAnnotationSchema: z.ZodDiscriminatedUnion<"type", [z.Z
     workflowId: z.ZodString;
     id: z.ZodString;
 }, "strip", z.ZodTypeAny, {
+    id: string;
     type: "edit";
     createdAt: string;
     workflowId: string;
-    id: string;
     beforeVersion: number;
     afterMarkdown: string;
     diff: string;
 }, {
+    id: string;
     type: "edit";
     createdAt: string;
     workflowId: string;
-    id: string;
     beforeVersion: number;
     afterMarkdown: string;
     diff: string;
@@ -87,17 +87,17 @@ export declare const DraftAnnotationSchema: z.ZodDiscriminatedUnion<"type", [z.Z
     workflowId: z.ZodString;
     id: z.ZodString;
 }, "strip", z.ZodTypeAny, {
+    id: string;
     type: "approve";
     version: number;
     createdAt: string;
     workflowId: string;
-    id: string;
 }, {
+    id: string;
     type: "approve";
     version: number;
     createdAt: string;
     workflowId: string;
-    id: string;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"reject">;
     version: z.ZodNumber;
@@ -106,18 +106,18 @@ export declare const DraftAnnotationSchema: z.ZodDiscriminatedUnion<"type", [z.Z
     workflowId: z.ZodString;
     id: z.ZodString;
 }, "strip", z.ZodTypeAny, {
+    id: string;
     type: "reject";
     version: number;
     createdAt: string;
     workflowId: string;
-    id: string;
     reason?: string | undefined;
 }, {
+    id: string;
     type: "reject";
     version: number;
     createdAt: string;
     workflowId: string;
-    id: string;
     reason?: string | undefined;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"resolve">;
@@ -127,17 +127,17 @@ export declare const DraftAnnotationSchema: z.ZodDiscriminatedUnion<"type", [z.Z
     workflowId: z.ZodString;
     id: z.ZodString;
 }, "strip", z.ZodTypeAny, {
+    id: string;
     type: "resolve";
     createdAt: string;
     workflowId: string;
-    id: string;
     commentId: string;
     resolved: boolean;
 }, {
+    id: string;
     type: "resolve";
     createdAt: string;
     workflowId: string;
-    id: string;
     commentId: string;
     resolved: boolean;
 }>, z.ZodObject<{
@@ -150,20 +150,20 @@ export declare const DraftAnnotationSchema: z.ZodDiscriminatedUnion<"type", [z.Z
     workflowId: z.ZodString;
     id: z.ZodString;
 }, "strip", z.ZodTypeAny, {
+    id: string;
     type: "address";
     version: number;
     createdAt: string;
     workflowId: string;
-    id: string;
     commentId: string;
     disposition: "addressed" | "deferred" | "wontfix";
     reason?: string | undefined;
 }, {
+    id: string;
     type: "address";
     version: number;
     createdAt: string;
     workflowId: string;
-    id: string;
     commentId: string;
     disposition: "addressed" | "deferred" | "wontfix";
     reason?: string | undefined;