@deskwork/studio 0.12.1 → 0.14.0

package/dist/pages/scrapbook.ts

@@ -1,247 +1,609 @@
 /**
- * Scrapbook viewer — `/dev/scrapbook/:site/<path>` (path may include `/`).
+ * Scrapbook viewer — `/dev/scrapbook/:site/<path>`.
  *
- * Reads the scrapbook directory at the given path and lists every
- * file with type chips + relative timestamps, plus secret items
- * (inside `scrapbook/secret/`) in a quiet second section. Empty
- * scrapbooks render an empty state with quick-add affordances.
+ * Issue #161 redesign: aside-left folder card with numbered item list,
+ * vertical card grid with per-kind colored ribbons + always-visible foot
+ * toolbar + per-kind preview rendering, drop zone, secret section,
+ * single-expanded card invariant, aside cross-linking.
  *
- * The `path` argument is the hierarchical address of the scrapbook —
- * any slash-separated kebab-case identifier under the site's
- * contentDir. It does not need to correspond to a calendar entry;
- * organizational nodes (e.g. `the-outbound/characters` with no
- * own README) can host their own scrapbooks too.
- *
- * Port of `pages/dev/scrapbook/[site]/[slug].astro`. Layout swap
- * (Astro `<Layout>` → studio shell) and CSS link added; structurally
- * similar otherwise.
+ * Mockup: docs/superpowers/frontend-design/2026-05-02-review-redesign/scrapbook-redesign.html
+ * Spec:   docs/superpowers/specs/2026-05-02-scrapbook-redesign-impl-spec.md
  */
 
+import { existsSync, readFileSync } from 'node:fs';
+import { readCalendar } from '@deskwork/core/calendar';
+import { findEntry } from '@deskwork/core/calendar-mutations';
+import { resolveCalendarPath } from '@deskwork/core/paths';
 import {
   formatRelativeTime,
   formatSize,
   listScrapbook,
+  scrapbookFilePath,
   type ScrapbookItem,
+  type ScrapbookItemKind,
 } from '@deskwork/core/scrapbook';
 import type { StudioContext } from '../routes/api.ts';
 import { html, unsafe, type RawHtml } from './html.ts';
 import { layout } from './layout.ts';
 import { renderEditorialFolio } from './chrome.ts';
 
-interface RenderItemRowOptions {
-  /** Mark the row visually as belonging to the secret section. */
-  secret?: boolean;
-  /**
-   * When true, render disclosure controls + toolbar. Both public AND
-   * secret rows now ship the toolbar (#28); the per-section tools
-   * include a "Mark secret" / "Mark public" toggle that the client
-   * resolves into a cross-section rename. Pre-#28 secret rows were
-   * read-only — that decision is reversed here so operators have full
-   * CRUD over secret/ items from the standalone viewer.
-   */
-  withTools?: boolean;
+const KIND_LABEL: Record<ScrapbookItemKind, string> = {
+  md: 'MD',
+  img: 'IMG',
+  json: 'JSON',
+  js: 'JS',
+  txt: 'TXT',
+  other: '·',
+};
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+/**
+ * Strip a YAML frontmatter block from the top of an md file. Only strips
+ * the leading `---\n...\n---\n` block; body-level `---` separators (Setext
+ * H2 underline, thematic break) are preserved because the function only
+ * looks at the first 4 chars for the opener.
+ */
+function stripFrontmatter(text: string): string {
+  if (!text.startsWith('---\n')) return text;
+  const closeIdx = text.indexOf('\n---\n', 4);
+  if (closeIdx < 0) return text;
+  return text.slice(closeIdx + 5).replace(/^\n+/, '');
+}
+
+/**
+ * Build the closed-state preview excerpt for md/json/txt. Returns null
+ * when there's nothing useful to render — empty file, frontmatter-only
+ * file, or binary masquerading as text — so the caller can omit the
+ * preview block entirely (matches "other" kind treatment, avoids the
+ * 6rem min-height void).
+ *
+ * For json: pretty-print via JSON.parse + JSON.stringify(_, null, 2) so
+ * minified single-line files still render multi-line. Falls back to raw
+ * content on parse error (bad JSON is still readable as text).
+ *
+ * Binary detection: NUL byte presence after UTF-8 decode. Real text
+ * almost never has NUL; binary files have it within the first KB.
+ */
+function previewExcerpt(buf: Buffer, kind: 'md' | 'json' | 'txt'): string | null {
+  let text = buf.subarray(0, Math.min(buf.byteLength, 2400)).toString('utf-8');
+  if (text.indexOf('\0') >= 0) return null;
+  if (kind === 'md') text = stripFrontmatter(text);
+  if (kind === 'json') {
+    try {
+      const fullText = buf.toString('utf-8');
+      text = JSON.stringify(JSON.parse(fullText), null, 2);
+    } catch {
+      // Invalid JSON — fall through to the raw-text excerpt below.
+    }
+  }
+  const excerpt = text.split('\n').slice(0, 8).join('\n').slice(0, 600);
+  if (excerpt.trim() === '') return null;
+  return excerpt;
+}
+
+/**
+ * Count lines in a text file: number of `\n` bytes plus 1 if the last
+ * byte isn't `\n` (so a 3-line file whether or not it has a trailing
+ * newline reports 3).
+ */
+function countLines(buf: Buffer): number {
+  let count = 0;
+  for (const b of buf) if (b === 0x0a) count++;
+  if (buf.length > 0 && buf[buf.length - 1] !== 0x0a) count++;
+  return count;
+}
+
+/**
+ * Count top-level keys in a JSON object. Returns null if the file is not
+ * valid JSON or its root is not a plain object (arrays, primitives →
+ * null; caller renders no extra meta).
+ */
+function countJsonKeys(buf: Buffer): number | null {
+  try {
+    const obj: unknown = JSON.parse(buf.toString('utf-8'));
+    if (obj !== null && typeof obj === 'object' && !Array.isArray(obj)) {
+      return Object.keys(obj).length;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+interface ImageDimensions { readonly width: number; readonly height: number; }
+
+/**
+ * Read width × height from a buffer. Recognizes PNG, JPEG, WebP, and
+ * GIF; returns null for unrecognized signatures or truncated/malformed
+ * buffers. Used by the scrapbook card meta to render `{W} × {H}` next
+ * to the image kind chip.
+ *
+ * Each format is parsed from its file-header structure (no external
+ * dependency); each branch returns null on any unexpected byte rather
+ * than throwing, so a corrupt image still renders with empty meta.
+ */
+function readImageDimensions(buf: Buffer): ImageDimensions | null {
+  if (buf.length < 12) return null;
+  // PNG: 89 50 4E 47 0D 0A 1A 0A then IHDR (chunk-length 4, "IHDR" 4,
+  // width 4, height 4 — width@16, height@20).
+  if (
+    buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47
+  ) {
+    if (buf.length < 24) return null;
+    return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+  }
+  // GIF: "GIF87a" or "GIF89a" + logical screen descriptor (width LE @6,
+  // height LE @8).
+  if (
+    buf[0] === 0x47 && buf[1] === 0x49 && buf[2] === 0x46 &&
+    buf[3] === 0x38 && (buf[4] === 0x37 || buf[4] === 0x39) && buf[5] === 0x61
+  ) {
+    if (buf.length < 10) return null;
+    return { width: buf.readUInt16LE(6), height: buf.readUInt16LE(8) };
+  }
+  // JPEG: starts FF D8. Width/height live in a Start-Of-Frame marker
+  // (FF C0–CF, excluding DHT C4 / JPG C8 / DAC CC). Walk markers
+  // skipping their payloads until the SOF is found.
+  if (buf[0] === 0xff && buf[1] === 0xd8) {
+    return readJpegDimensions(buf);
+  }
+  // WebP: "RIFF" {size} "WEBP" then a chunk (VP8 / VP8L / VP8X).
+  if (
+    buf[0] === 0x52 && buf[1] === 0x49 && buf[2] === 0x46 && buf[3] === 0x46 &&
+    buf[8] === 0x57 && buf[9] === 0x45 && buf[10] === 0x42 && buf[11] === 0x50
+  ) {
+    return readWebpDimensions(buf);
+  }
+  return null;
+}
+
+function readJpegDimensions(buf: Buffer): ImageDimensions | null {
+  // Marker walk: skip FF D8 (SOI), then each marker is FF Xn followed
+  // by a 2-byte big-endian segment length (which includes its own 2
+  // bytes). The SOF segment's payload is: 1 byte precision, 2 bytes
+  // height, 2 bytes width (the rest is component info).
+  let i = 2;
+  while (i + 4 <= buf.length) {
+    if (buf[i] !== 0xff) return null;
+    let marker = buf[i + 1] ?? 0;
+    // Skip fill bytes (0xff padding before the actual marker byte).
+    while (marker === 0xff && i + 2 < buf.length) {
+      i++;
+      marker = buf[i + 1] ?? 0;
+    }
+    i += 2;
+    // Standalone markers (no length): RST0–7 (D0–D7) and SOI/EOI/TEM.
+    if (marker === 0xd9 || marker === 0xd8 || marker === 0x01) return null;
+    if (marker >= 0xd0 && marker <= 0xd7) continue;
+    if (i + 2 > buf.length) return null;
+    const segLen = buf.readUInt16BE(i);
+    // SOF markers carry the dimensions. Exclusions per JPEG spec:
+    // C4 (DHT — Huffman tables), C8 (JPG reserved), CC (DAC — arithmetic
+    // coding conditioning).
+    const isSof =
+      marker >= 0xc0 && marker <= 0xcf &&
+      marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
+    if (isSof) {
+      if (i + 7 > buf.length) return null;
+      return {
+        width: buf.readUInt16BE(i + 5),
+        height: buf.readUInt16BE(i + 3),
+      };
+    }
+    i += segLen;
+  }
+  return null;
 }
 
-function renderItemRow(
+function readWebpDimensions(buf: Buffer): ImageDimensions | null {
+  // Three sub-formats (per RFC 6386 / VP8L spec / WebP container spec):
+  //   - "VP8 " (lossy):     header @20-22: signature 9D 01 2A, then
+  //                          14-bit width LE @23, 14-bit height LE @25
+  //                          (each masked to 14 bits — top 2 bits are
+  //                          horizontal/vertical scale).
+  //   - "VP8L" (lossless):  header @20: signature 0x2F, then 32 bits
+  //                          packed: width-1 (14 bits) + height-1 (14
+  //                          bits) + alpha-flag + version (4 bits).
+  //   - "VP8X" (extended):  flags @20, reserved @21-23, width-1 (24
+  //                          bits LE) @24, height-1 (24 bits LE) @27.
+  // Need at least the RIFF header + chunk fourcc; per-variant length
+  // checks below cover the variant-specific payload sizes.
+  if (buf.length < 16) return null;
+  const fourcc = buf.subarray(12, 16).toString('ascii');
+  if (fourcc === 'VP8 ') {
+    if (buf.length < 30) return null;
+    if (buf[23] !== 0x9d || buf[24] !== 0x01 || buf[25] !== 0x2a) return null;
+    const w = buf.readUInt16LE(26) & 0x3fff;
+    const h = buf.readUInt16LE(28) & 0x3fff;
+    return { width: w, height: h };
+  }
+  if (fourcc === 'VP8L') {
+    if (buf.length < 25) return null;
+    if (buf[20] !== 0x2f) return null;
+    // Read 4 bytes LE at offset 21, then unpack.
+    const packed = buf.readUInt32LE(21);
+    const widthMinus1 = packed & 0x3fff;
+    const heightMinus1 = (packed >>> 14) & 0x3fff;
+    return { width: widthMinus1 + 1, height: heightMinus1 + 1 };
+  }
+  if (fourcc === 'VP8X') {
+    if (buf.length < 30) return null;
+    // 24-bit little-endian: low byte + (mid << 8) + (high << 16).
+    const w =
+      ((buf[24] ?? 0) | ((buf[25] ?? 0) << 8) | ((buf[26] ?? 0) << 16)) + 1;
+    const h =
+      ((buf[27] ?? 0) | ((buf[28] ?? 0) << 8) | ((buf[29] ?? 0) << 16)) + 1;
+    return { width: w, height: h };
+  }
+  return null;
+}
+
+/**
+ * Compute the per-kind extra meta string shown after the kind chip + size:
+ *   md / txt → "{N} lines"
+ *   json     → "{N} keys" (root must be a plain object; otherwise empty)
+ *   img      → "{W} × {H}" (PNG only; other formats → empty)
+ *   other    → empty
+ *
+ * ENOENT (race-window with delete) returns empty so the card still
+ * renders; other errors propagate to the page renderer.
+ */
+function computeKindMeta(
+  ctx: StudioContext,
+  site: string,
+  path: string,
   item: ScrapbookItem,
-  index: number,
-  opts: RenderItemRowOptions = {},
-): RawHtml {
-  const { secret = false, withTools = true } = opts;
-  const editBtn =
-    withTools && item.kind === 'md'
-      ? unsafe(html`<button type="button" class="scrapbook-tool" data-action="edit">edit</button>`)
-      : '';
-  const seq = String(index + 1).padStart(2, '0');
-  const kindLabel = item.kind === 'other' ? '·' : item.kind.toUpperCase();
-  const idPrefix = secret ? 'secret-' : '';
-  const dataSecret = secret ? ' data-secret="true"' : '';
-  // The "mark secret/public" toggle is the cross-section rename
-  // affordance. The button label flips with the source section.
-  const sectionToggleLabel = secret ? 'mark public' : 'mark secret';
-  const toolbar = withTools
-    ? unsafe(html`<div class="scrapbook-toolbar" data-toolbar>
-        ${editBtn}
-        <button type="button" class="scrapbook-tool" data-action="rename">rename</button>
-        <button type="button" class="scrapbook-tool" data-action="toggle-secret">${sectionToggleLabel}</button>
-        <button type="button" class="scrapbook-tool scrapbook-tool--delete" data-action="delete">delete</button>
-      </div>`)
-    : '';
-  return unsafe(html`
-    <li class="scrapbook-item${secret ? ' scrapbook-item--secret' : ''}" data-state="closed" data-open="false"
-      data-filename="${item.name}" data-kind="${item.kind}"
-      data-size="${item.size}" data-mtime="${item.mtime}"${unsafe(dataSecret)}
-      id="${idPrefix}item-${encodeURIComponent(item.name)}">
-      <button type="button" class="scrapbook-item-header" aria-expanded="false">
-        <span class="scrapbook-seq" aria-hidden="true">§ ${seq}</span>
-        <span class="scrapbook-kind scrapbook-kind--${item.kind}" aria-hidden="true">${kindLabel}</span>
-        <span class="scrapbook-filename" data-filename-cell>${item.name}</span>
-        <time class="scrapbook-mtime" datetime="${item.mtime}">${formatRelativeTime(item.mtime)}</time>
-        <span class="scrapbook-disclosure" aria-hidden="true">▸</span>
-      </button>
-      ${toolbar}
-      <div class="scrapbook-perforation" aria-hidden="true"></div>
-      <div class="scrapbook-item-body" data-body>
-        <div data-body-content></div>
-      </div>
-    </li>`);
+): string {
+  if (item.kind !== 'md' && item.kind !== 'txt' && item.kind !== 'json' && item.kind !== 'img') {
+    return '';
+  }
+  let buf: Buffer;
+  try {
+    const fullPath = scrapbookFilePath(ctx.projectRoot, ctx.config, site, path, item.name);
+    buf = readFileSync(fullPath);
+  } catch (e) {
+    if (e instanceof Error && 'code' in e && e.code === 'ENOENT') return '';
+    throw e;
+  }
+  if (item.kind === 'md' || item.kind === 'txt') return `${countLines(buf)} lines`;
+  if (item.kind === 'json') {
+    const keys = countJsonKeys(buf);
+    return keys !== null ? `${keys} keys` : '';
+  }
+  // img
+  const dims = readImageDimensions(buf);
+  return dims ? `${dims.width} × ${dims.height}` : '';
 }
 
 /**
- * Build a hierarchical breadcrumb from the path. Each segment links to
- * the scrapbook view for its prefix. The root segment (site) just
- * goes back to the editorial dashboard.
+ * Server-side preview for the closed-state card. Img → bg-frame URL;
+ * md → italic Newsreader excerpt with frontmatter stripped; json → mono
+ * pre with parse-then-stringify pretty-print; txt → mono pre raw excerpt.
+ * Other / empty / binary-as-text → no preview block.
  */
-function renderBreadcrumb(site: string, path: string): RawHtml {
-  const segments = path.split('/');
-  const links: string[] = [];
-  for (let i = 0; i < segments.length; i++) {
-    const prefix = segments.slice(0, i + 1).join('/');
-    const isLast = i === segments.length - 1;
-    if (isLast) {
-      links.push(html`<span class="scrapbook-breadcrumb-current">${segments[i]}</span>`);
-    } else {
-      links.push(
-        html`<a class="scrapbook-breadcrumb-link" href="/dev/scrapbook/${site}/${prefix}">${segments[i]}</a>`,
-      );
+function renderPreview(
+  ctx: StudioContext,
+  site: string,
+  path: string,
+  item: ScrapbookItem,
+  opts: { secret?: boolean } = {},
+): RawHtml {
+  const { secret = false } = opts;
+  if (item.kind === 'img') {
+    const params = new URLSearchParams({ site, path, name: item.name });
+    if (secret) params.set('secret', '1');
+    const url = `/api/dev/scrapbook-file?${params.toString()}`;
+    return unsafe(html`
+      <div class="scrap-preview scrap-preview--img" aria-hidden="true">
+        <div class="scrap-preview--img-frame" style="background-image: url(&quot;${url}&quot;);"></div>
+      </div>`);
+  }
+  if (item.kind !== 'md' && item.kind !== 'txt' && item.kind !== 'json') {
+    return unsafe('');
+  }
+  try {
+    const fullPath = scrapbookFilePath(
+      ctx.projectRoot,
+      ctx.config,
+      site,
+      path,
+      item.name,
+      secret ? { secret: true } : {},
+    );
+    const buf = readFileSync(fullPath);
+    const excerpt = previewExcerpt(buf, item.kind);
+    if (excerpt === null) return unsafe('');
+    const safe = escapeHtml(excerpt);
+    if (item.kind === 'json' || item.kind === 'txt') {
+      return unsafe(html`
+        <pre class="scrap-preview scrap-preview--mono" aria-hidden="true">${unsafe(safe)}</pre>`);
+    }
+    return unsafe(html`
+      <div class="scrap-preview scrap-preview-md" aria-hidden="true"><p>${unsafe(safe)}</p></div>`);
+  } catch (e) {
+    // ENOENT = file disappeared between listScrapbook and this read (race
+    // window with delete); rendering an empty preview is the right call.
+    // Anything else (EACCES, EISDIR, encoding bugs) propagates so the
+    // operator sees a real error instead of a silently-broken page.
+    if (e instanceof Error && 'code' in e && e.code === 'ENOENT') {
+      return unsafe('');
     }
+    throw e;
   }
-  const sep = '<span class="scrapbook-breadcrumb-sep" aria-hidden="true">›</span>';
-  const joined = links.join(`\n${sep}\n`);
+}
+
+interface KindCounts {
+  all: number;
+  md: number;
+  img: number;
+  json: number;
+  js: number;
+  txt: number;
+  other: number;
+}
+
+function countByKind(items: readonly ScrapbookItem[]): KindCounts {
+  const counts: KindCounts = {
+    all: items.length,
+    md: 0,
+    img: 0,
+    json: 0,
+    js: 0,
+    txt: 0,
+    other: 0,
+  };
+  for (const i of items) counts[i.kind]++;
+  return counts;
+}
+
+function renderFilterChips(counts: KindCounts): RawHtml {
+  const chip = (kind: keyof KindCounts, label: string, isAll = false): RawHtml =>
+    unsafe(html`
+    <button class="scrap-filter" type="button" data-filter="${kind}"
+      aria-pressed="${isAll ? 'true' : 'false'}">${label} · ${counts[kind]}</button>`);
   return unsafe(html`
-    <nav class="scrapbook-breadcrumb" aria-label="scrapbook hierarchy">
-      <a class="scrapbook-breadcrumb-link" href="/dev/editorial-studio">${site}</a>
-      <span class="scrapbook-breadcrumb-sep" aria-hidden="true">›</span>
-      ${unsafe(joined)}
+    <div class="scrap-filters" role="toolbar" aria-label="filter by kind">
+      ${chip('all', 'all', true)}
+      ${chip('md', 'md')}
+      ${chip('img', 'img')}
+      ${chip('json', 'json')}
+      ${chip('txt', 'txt')}
+      ${chip('other', 'other')}
+    </div>`);
+}
+
+function renderSearch(): RawHtml {
+  return unsafe(html`
+    <div class="scrap-search">
+      <input type="search" placeholder="filter by name or content" aria-label="filter scrapbook" data-scrap-search />
+      <span class="scrap-search-kbd">/</span>
+    </div>`);
+}
+
+function renderBreadcrumb(site: string, path: string): RawHtml {
+  const segments = path.split('/').filter(Boolean);
+  const last = segments[segments.length - 1] ?? path;
+  return unsafe(html`
+    <nav class="scrap-breadcrumb" aria-label="hierarchy">
+      <a href="/dev/content/${site}">${site}</a><span class="sep">›</span>
+      <b>${last}</b>
     </nav>`);
 }
 
-function renderIndexSidebar(items: readonly ScrapbookItem[], site: string, path: string): RawHtml {
-  const totalBytes = items.reduce((acc, item) => acc + item.size, 0);
-  const lastModified =
-    items.length > 0
-      ? items.reduce((a, b) => (a.mtime > b.mtime ? a : b)).mtime
-      : null;
+function renderAside(
+  site: string,
+  path: string,
+  items: readonly ScrapbookItem[],
+  totalSize: number,
+  lastModified: string | null,
+  secretCount: number,
+  reviewLink: string | null,
+): RawHtml {
+  const lastModifiedLabel = lastModified ? formatRelativeTime(lastModified) : '—';
+  const publicCount = items.length;
+  const sizeLabel = formatSize(totalSize);
+  const folderLabel = path.split('/').filter(Boolean).pop() ?? path;
+  const fullPath = `${site}/${path}/scrapbook/`;
+  // #168 Phase 34 ship-pass — when this scrapbook belongs to a tracked
+  // calendar entry, expose a "← back to review" link so the operator
+  // who arrived from the entry-review surface (or via the dashboard's
+  // scrapbook chip) has an obvious path back. Pre-fix the only nav
+  // affordance was the breadcrumb's site link, which lands on the
+  // content tree, not the entry-review.
+  const backLink: RawHtml = reviewLink !== null
+    ? unsafe(html`<p class="scrap-aside-back"><a href="${reviewLink}">← back to review</a></p><hr />`)
+    : unsafe('');
   return unsafe(html`
-    <aside class="scrapbook-index">
-      <p class="scrapbook-index-kicker">
-        <span aria-hidden="true">§</span> The folder
+    <aside class="scrap-aside">
+      ${backLink}
+      <p class="scrap-aside-kicker"><em>§</em> The folder</p>
+      <h1 class="scrap-aside-title">${folderLabel}</h1>
+      <p class="scrap-aside-meta">${site}</p>
+      <hr />
+      <p class="scrap-aside-totals">
+        <strong>${publicCount}</strong> public ·
+        <strong>${secretCount}</strong> secret ·
+        <em>${sizeLabel}</em>
       </p>
-      <p class="scrapbook-index-meta">${path}</p>
-      <p class="scrapbook-index-meta">${site}</p>
+      <p class="scrap-aside-meta">last modified ${lastModifiedLabel}</p>
       <hr />
-      <ol class="scrapbook-index-list" data-scrapbook-index>
-        ${items.map(
-          (item, i) => unsafe(html`<li data-index-for="${item.name}">
-            <span class="scrapbook-index-num">No. ${String(i + 1).padStart(2, '0')}</span>
-            <a href="#item-${encodeURIComponent(item.name)}">${item.name}</a>
-          </li>`),
-        )}
+      <ol class="scrap-aside-list" data-scrap-aside-list>
+        ${items.map((item, i) => {
+          const seq = String(i + 1).padStart(2, '0');
+          return unsafe(html`<li><span class="num">${seq}</span><a href="#item-${i + 1}" data-scrap-aside-link>${item.name}</a></li>`);
+        })}
       </ol>
       <hr />
-      <p class="scrapbook-index-totals">${items.length} ${items.length === 1 ? 'item' : 'items'} · ${formatSize(totalBytes)}</p>
-      ${
-        lastModified
-          ? unsafe(html`<p class="scrapbook-index-subtotal">last modified ${formatRelativeTime(lastModified)}</p>`)
-          : ''
-      }
-      <hr />
-      <div class="scrapbook-index-actions">
-        <button type="button" class="scrapbook-index-btn" data-action="new-note">+ new note</button>
-        <button type="button" class="scrapbook-index-btn" data-action="upload">+ upload file</button>
+      <div class="scrap-aside-actions">
+        <button class="scrap-aside-btn scrap-aside-btn--primary" type="button" data-action="new-note">+ new note</button>
+        <button class="scrap-aside-btn" type="button" data-action="upload">+ upload file</button>
       </div>
       <hr />
-      <p class="scrapbook-index-path">${site}/${path}/scrapbook/</p>
+      <p class="scrap-aside-path">${fullPath}</p>
     </aside>`);
 }
 
-function renderEmpty(): RawHtml {
+function renderCard(
+  ctx: StudioContext,
+  site: string,
+  path: string,
+  item: ScrapbookItem,
+  index: number,
+  opts: { secret?: boolean } = {},
+): RawHtml {
+  const { secret = false } = opts;
+  const seq = String(index + 1).padStart(2, '0');
+  const kindLabel = KIND_LABEL[item.kind];
+  const kindClass = item.kind === 'other' ? '' : `scrap-kind--${item.kind}`;
+  const time = item.mtime
+    ? html`<time class="scrap-time" datetime="${item.mtime}">${formatRelativeTime(item.mtime)}</time>`
+    : '';
+  const preview = renderPreview(ctx, site, path, item, { secret });
+  const kindMeta = computeKindMeta(ctx, site, path, item);
+  const kindMetaHtml: RawHtml = kindMeta
+    ? unsafe(html`<span>·</span><span>${kindMeta}</span>`)
+    : unsafe('');
+  const editBtn = item.kind === 'img'
+    ? unsafe('')
+    : unsafe(html`<button class="scrap-tool" type="button" data-action="edit">edit</button>`);
+  // Secret cards get id="secret-item-N" to disambiguate from public ids in
+  // restoreFromHash + aside cross-link lookups (F4 contract); the
+  // mark-secret action toggle reads "mark public" since clicking it moves
+  // the card OUT of the secret section.
+  const id = secret ? `secret-item-${index + 1}` : `item-${index + 1}`;
+  const markSecretLabel = secret ? 'mark public' : 'mark secret';
+  const dataSecretAttr = secret ? ' data-secret="true"' : '';
+  // #164 Phase 34b — small ⚿ glyph next to .scrap-name on secret
+  // cards. Provides visual continuity for the secret marker once a
+  // card is expanded (where it grows outside the grouped section's
+  // visual scope).
+  const secretGlyph: RawHtml = secret
+    ? unsafe(html`<span class="scrap-name-secret-mark" aria-label="secret" title="secret — never published">⚿</span>`)
+    : unsafe('');
   return unsafe(html`
-    <section class="scrapbook-empty">
-      <p>
-        This scrapbook is empty. Write the first note, or drop a file
-        anywhere on this page.
-      </p>
-      <div class="scrapbook-empty-actions">
-        <button type="button" class="scrapbook-index-btn" data-action="new-note">+ new note</button>
-        <button type="button" class="scrapbook-index-btn" data-action="upload">+ upload file</button>
+    <li class="scrap-card" data-kind="${item.kind}" data-state="closed" id="${id}"${unsafe(dataSecretAttr)}>
+      <div class="scrap-card-head">
+        <span class="scrap-seq">N° ${seq}</span>
+        ${secretGlyph}
+        <span class="scrap-name" data-action="open">${item.name}</span>
+        ${unsafe(time)}
       </div>
-    </section>`);
+      <div class="scrap-card-meta">
+        <span class="scrap-kind ${kindClass}">${kindLabel}</span>
+        <span class="scrap-size">${formatSize(item.size)}</span>
+        ${kindMetaHtml}
+      </div>
+      ${preview}
+      <div class="scrap-card-foot">
+        <button class="scrap-tool scrap-tool--primary" type="button" data-action="open">open</button>
+        ${editBtn}
+        <button class="scrap-tool" type="button" data-action="rename">rename</button>
+        <button class="scrap-tool" type="button" data-action="mark-secret">${markSecretLabel}</button>
+        <span class="spacer"></span>
+        <button class="scrap-tool scrap-tool--delete" type="button" data-action="delete">delete</button>
+      </div>
+    </li>`);
 }
 
-function renderReadingPanel(items: readonly ScrapbookItem[]): RawHtml {
+/**
+ * Inline new-note composer (Phase 34b — #166).
+ *
+ * Mirrors the pre-F1 inline composer (`44094ee^:scrapbook.ts:274-294`),
+ * adapted to the F1 `.scrap-*` design vocabulary. Hidden by default;
+ * the aside's `+ new note` button reveals it via the client wire-up.
+ *
+ * Per `.claude/rules/affordance-placement.md`: component-attached to
+ * the page (not a generic toolbar), placed where the resulting note
+ * will appear in sorted position. Direct manipulation: in-page form,
+ * filename + body + secret toggle visible inline, Cmd/Ctrl+S saves,
+ * Esc cancels. Replaces the F1 `window.prompt()` regression (#166).
+ */
+function renderComposer(): RawHtml {
   return unsafe(html`
-    <section class="scrapbook-reading">
-      <form class="scrapbook-composer" data-scrapbook-composer hidden>
-        <div class="scrapbook-composer-header">
-          <span class="scrapbook-composer-seq" aria-hidden="true">✎</span>
-          <span class="scrapbook-composer-kind">NEW</span>
-          <input type="text" class="scrapbook-composer-filename" data-composer-filename
-            placeholder="note-name.md" aria-label="new note filename" />
-          <div class="scrapbook-editor-footer scrapbook-composer-actions">
-            <label class="scrapbook-secret-toggle" title="save under scrapbook/secret/ — never published">
-              <input type="checkbox" data-composer-secret />
-              <span>secret</span>
-            </label>
-            <button type="button" class="scrapbook-tool" data-action="composer-cancel">cancel</button>
-            <button type="submit" class="scrapbook-tool scrapbook-tool--primary" data-action="composer-save">save →</button>
-          </div>
-        </div>
-        <div class="scrapbook-composer-body">
-          <textarea data-composer-body
-            placeholder="Write the note in markdown. Cmd/Ctrl+S saves."
-            aria-label="new note body"></textarea>
-        </div>
-      </form>
-      <ol class="scrapbook-items" data-scrapbook-items>
-        ${items.map((item, i) => renderItemRow(item, i))}
-      </ol>
-      <div class="scrapbook-drop" data-scrapbook-drop role="button" tabindex="0"
-        aria-label="upload a file to the scrapbook">
-        <span class="scrapbook-drop-label">── drop a file here, or pick one ──</span>
-        <input type="file" data-scrapbook-file-input
-          accept="image/*,application/json,text/plain,text/markdown,.md,.json,.txt" />
-        <label class="scrapbook-secret-toggle scrapbook-secret-toggle--upload"
-          title="save the upload under scrapbook/secret/ — never published">
-          <input type="checkbox" data-upload-secret />
-          <span>upload as secret</span>
+    <form class="scrap-composer" data-scrap-composer hidden>
+      <header class="scrap-composer-head">
+        <span class="scrap-composer-glyph" aria-hidden="true">✎</span>
+        <span class="scrap-composer-kicker">NEW NOTE</span>
+        <input type="text" class="scrap-composer-filename" data-composer-filename
+          placeholder="note-name.md" aria-label="new note filename" />
+        <label class="scrap-composer-secret" title="save under scrapbook/secret/ — never published">
+          <input type="checkbox" data-composer-secret />
+          <span>secret</span>
         </label>
-      </div>
-    </section>`);
+        <button class="scrap-tool" type="button" data-action="composer-cancel">cancel</button>
+        <button class="scrap-tool scrap-tool--primary" type="submit" data-action="composer-save">save →</button>
+      </header>
+      <textarea class="scrap-composer-body" data-composer-body
+        placeholder="Write the note in markdown. Cmd/Ctrl+S saves, Esc cancels."
+        aria-label="new note body" rows="8"></textarea>
+    </form>`);
 }
 
-/**
- * Quiet second section listing items inside `scrapbook/secret/`. Read-
- * only in v1 — operators populate the directory by hand or via the
- * core API; the studio surface just shows what's there. The "private"
- * badge gives unmistakable visual differentiation from the public
- * items above.
- */
-function renderSecretSection(items: readonly ScrapbookItem[]): RawHtml {
+function renderDropZone(): RawHtml {
+  return unsafe(html`
+    <div class="scrap-drop" role="button" tabindex="0" data-action="upload"
+         aria-label="Drop a file here, or press Enter to pick one">
+      ── drop a file here, or pick one ──
+    </div>`);
+}
+
+function renderSecretSection(
+  ctx: StudioContext,
+  site: string,
+  path: string,
+  secretItems: readonly ScrapbookItem[],
+): RawHtml {
+  if (secretItems.length === 0) return unsafe('');
+  const cards = secretItems.map((item, i) => renderCard(ctx, site, path, item, i, { secret: true }));
   return unsafe(html`
-    <section class="scrapbook-secret" data-scrapbook-secret>
-      <header class="scrapbook-secret-header">
-        <span class="scrapbook-secret-mark" aria-hidden="true">⚿</span>
-        <h2 class="scrapbook-secret-title">Secret</h2>
-        <span class="scrapbook-secret-badge" aria-label="private — never published">
-          private
-        </span>
-        <span class="scrapbook-secret-count">
-          ${items.length} ${items.length === 1 ? 'item' : 'items'}
-        </span>
+    <section class="scrap-secret" aria-label="secret items">
+      <header class="scrap-secret-head">
+        <span class="scrap-secret-mark" aria-hidden="true">⚿</span>
+        <h2 class="scrap-secret-title">Secret</h2>
+        <span class="scrap-secret-badge">private — never published</span>
       </header>
-      <p class="scrapbook-secret-help">
-        Items inside <code>scrapbook/secret/</code>. Excluded from the
-        public site by the host's content-collection patterns.
-      </p>
-      <ol class="scrapbook-items scrapbook-items--secret">
-        ${items.map((item, i) =>
-          renderItemRow(item, i, { secret: true, withTools: true }),
-        )}
+      <ol class="scrap-cards">
+        ${cards}
       </ol>
     </section>`);
 }
 
+/**
+ * #168 Phase 34 ship-pass — when the scrapbook path matches a tracked
+ * calendar entry with a stamped UUID, return the entry-keyed review
+ * URL so the aside can render a "← back to review" link. Returns null
+ * when no entry matches (organizational subdirs, ad-hoc paths, or
+ * pre-doctor entries lacking an id) — the link is then omitted.
+ *
+ * Failures (calendar absent, parse error) fall through to null so a
+ * transient calendar issue never blocks the scrapbook render.
+ */
+function lookupEntryReviewLink(
+  ctx: StudioContext,
+  site: string,
+  path: string,
+): string | null {
+  if (!(site in ctx.config.sites)) return null;
+  try {
+    const calendarPath = resolveCalendarPath(ctx.projectRoot, ctx.config, site);
+    if (!existsSync(calendarPath)) return null;
+    const cal = readCalendar(calendarPath);
+    const entry = findEntry(cal, path);
+    if (!entry || !entry.id) return null;
+    return `/dev/editorial-review/entry/${entry.id}`;
+  } catch {
+    return null;
+  }
+}
+
 export function renderScrapbookPage(
   ctx: StudioContext,
   site: string,
@@ -253,46 +615,51 @@ export function renderScrapbookPage(
   if (!(site in ctx.config.sites)) {
     throw new Error(`unknown site: ${site}`);
   }
-  const summary = listScrapbook(ctx.projectRoot, ctx.config, site, path);
-  const items = summary.items;
-  const secretItems = summary.secretItems;
-
-  const publicBlock =
-    items.length === 0
-      ? renderEmpty().__raw
-      : renderReadingPanel(items).__raw + renderIndexSidebar(items, site, path).__raw;
-
-  const secretBlock = secretItems.length > 0 ? renderSecretSection(secretItems).__raw : '';
-
+  // listScrapbook returns { exists: false, items: [] } for missing dirs
+  // (packages/core/src/scrapbook.ts:337-339), so an empty scrapbook is not
+  // an error path. Real errors (slug validation, scrapbookDir resolution
+  // failures, FS permission issues) propagate to the studio's error handler.
+  const result = listScrapbook(ctx.projectRoot, ctx.config, site, path);
+  const items = result.items;
+  const secretItems = result.secretItems;
+  const totalSize = items.reduce((s, i) => s + i.size, 0);
+  const lastModified = items.reduce<string | null>((acc, i) => {
+    if (!i.mtime) return acc;
+    if (!acc || i.mtime > acc) return i.mtime;
+    return acc;
+  }, null);
+  const counts = countByKind(items);
+  const folderLabel = path.split('/').filter(Boolean).pop() ?? path;
+  const cards = items.map((item, i) => renderCard(ctx, site, path, item, i));
+  const cardsHtml = cards.map((c) => c.__raw).join('');
+  const reviewLink = lookupEntryReviewLink(ctx, site, path);
   const body = html`
     ${renderEditorialFolio('content', `scrapbook · ${site}/${path}`)}
-    <main class="scrapbook-page" data-site="${site}" data-slug="${path}" data-scrapbook-root>
-      <header class="er-pagehead er-pagehead--compact scrapbook-header">
-        ${renderBreadcrumb(site, path)}
-        <p class="er-pagehead__kicker scrapbook-kicker">
-          <span class="scrapbook-kicker-mark" aria-hidden="true">§</span>
-          Scrapbook
-        </p>
-        <h1 class="er-pagehead__title scrapbook-title">${path}</h1>
-        <a class="scrapbook-back" href="/dev/editorial-studio">← back to the desk</a>
-      </header>
-      <div class="scrapbook-status" data-scrapbook-status hidden></div>
-      ${unsafe(publicBlock)}
-      ${unsafe(secretBlock)}
-      <div class="scrapbook-drop-overlay" data-scrapbook-overlay aria-hidden="true">
-        <span class="scrapbook-drop-overlay-text">drop to add to the scrapbook ◇</span>
-      </div>
+    <main class="scrap-page" data-site="${site}" data-path="${path}">
+      ${renderAside(site, path, items, totalSize, lastModified, secretItems.length, reviewLink)}
+      <section class="scrap-main">
+        <header class="scrap-main-header">
+          ${renderBreadcrumb(site, path)}
+          ${renderSearch()}
+        </header>
+        ${renderFilterChips(counts)}
+        ${renderComposer()}
+        <ol class="scrap-cards" id="cards" data-scrap-cards>
+          ${unsafe(cardsHtml)}
+        </ol>
+        ${renderDropZone()}
+        ${renderSecretSection(ctx, site, path, secretItems)}
+      </section>
     </main>`;
-
   return layout({
-    title: `scrapbook · ${path} — dev`,
+    title: `scrapbook · ${folderLabel} — dev`,
     cssHrefs: [
       '/static/css/editorial-review.css',
       '/static/css/editorial-nav.css',
       '/static/css/scrapbook.css',
       '/static/css/blog-figure.css',
     ],
-    bodyAttrs: 'data-review-ui="studio"',
+    bodyAttrs: 'data-review-ui="scrapbook"',
     bodyHtml: body,
     scriptModules: ['scrapbook-client'],
   });