@tinytars/frame 0.1.1 → 0.1.3

package/pdf-render.ts

@@ -0,0 +1,48 @@
+// Lazy pdfjs-dist loader, shared by AttachmentViewer.svelte (the full in-app PDF viewer) and
+// PdfThumbnail.svelte (a reports list's first-page preview). pdfjs-dist (~500 KB) is deliberately
+// kept out of the main render bundle; this dynamic import is the only place in the rendering path
+// that pulls it in, and only once a PDF actually needs to be shown as pixels.
+let pdfjsPromise: Promise<typeof import("pdfjs-dist/legacy/build/pdf.mjs")> | null = null;
+
+async function loadPdfjs() {
+  if (!pdfjsPromise) {
+    pdfjsPromise = import("pdfjs-dist/legacy/build/pdf.mjs").then(async (pdfjs) => {
+      const workerUrl = (await import("pdfjs-dist/legacy/build/pdf.worker.mjs?url")).default;
+      pdfjs.GlobalWorkerOptions.workerSrc = workerUrl;
+      return pdfjs;
+    });
+  }
+  return pdfjsPromise;
+}
+
+export interface PdfDoc {
+  numPages: number;
+  renderPage(pageNum: number, canvas: HTMLCanvasElement, maxWidth?: number): Promise<void>;
+}
+
+// `source` is either a URL (fetched by the caller's own API route) or raw bytes.
+export async function openPdf(source: string | Uint8Array): Promise<PdfDoc> {
+  const pdfjs = await loadPdfjs();
+  const params = typeof source === "string" ? { url: source } : { data: source };
+  // isEvalSupported:false — same runtime option parsers/report.ts and parsers/dexa.ts already set
+  // (missing from the legacy build's DocumentInitParameters typing there too). The url|data union
+  // here doesn't structurally match DocumentInitParameters closely enough for a direct `as`, hence
+  // the double cast via unknown (same reason TS gives for suggesting it).
+  const doc = await pdfjs.getDocument(
+    { ...params, isEvalSupported: false } as unknown as Parameters<typeof pdfjs.getDocument>[0],
+  ).promise;
+  return {
+    numPages: doc.numPages,
+    async renderPage(pageNum: number, canvas: HTMLCanvasElement, maxWidth = 900) {
+      const page = await doc.getPage(pageNum);
+      const unscaled = page.getViewport({ scale: 1 });
+      const scale = maxWidth / unscaled.width;
+      const viewport = page.getViewport({ scale });
+      canvas.width = viewport.width;
+      canvas.height = viewport.height;
+      const ctx = canvas.getContext("2d");
+      if (!ctx) return;
+      await page.render({ canvasContext: ctx, canvas, viewport }).promise;
+    },
+  };
+}

package/persisted-json.ts

@@ -0,0 +1,17 @@
+// Generic localStorage JSON persistence primitive. One place to get "load with a fallback, save
+// silently no-op'ing outside the browser" right, instead of each caller hand-rolling its own pair.
+export function loadJSON<T>(key: string, fallback: T): T {
+  if (typeof localStorage === "undefined") return fallback;
+  const raw = localStorage.getItem(key);
+  if (raw === null) return fallback;
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+export function saveJSON<T>(key: string, value: T): void {
+  if (typeof localStorage === "undefined") return;
+  localStorage.setItem(key, JSON.stringify(value));
+}

package/sidebar-rows.ts

@@ -0,0 +1,47 @@
+// The two row SHAPES the sidebar renders, as a plain .ts module.
+//
+// A type exported from a .svelte file can only be resolved by svelte-check, never by plain `tsc`.
+// These two were declared inside SidebarLeafList.svelte / SidebarGroupList.svelte and imported by
+// pure modules that build sidebar rows, which put those modules — and any Node-side script that
+// imports them — beyond the reach of any Node-side type check. The components keep the rendering;
+// the shape lives here.
+
+export interface SidebarLeafRow {
+  key: string;
+  label: string;
+  anchor: string;
+  pinned?: boolean;
+  // The vault record this row stands for, when the row's own `key` is not that id — Hypothesis
+  // keys its rows positionally (topic+side+index, because that is what its anchor needs) while
+  // the record behind a patient idea is a DecisionEntry. `undefined` means "key IS the id";
+  // `null` means "this row has no record at all" (an AI-proposed idea), so it cannot be pinned.
+  itemId?: string | null;
+  // Falls back to `label` when absent — lets a truncated label (e.g. Notes' preview text) still
+  // filter against the full underlying text.
+  searchText?: string;
+  // An id to put on the row element itself. Only set where the SIDEBAR row is the only place that
+  // item exists (Chat's threads) — everywhere else the main panel already owns the anchor id, and
+  // a duplicate would capture getElementById and break scroll-to.
+  domId?: string;
+}
+
+export interface SidebarGroupRow {
+  key: string;
+  label: string;
+  count?: number;
+  title?: string;
+  // Optional per-row quick-add, for group rows that are really navigation targets in disguise
+  // rather than an in-page filter. Same class/aria-label convention as the top-level row's own
+  // `.side-row-action` so a caller's existing selectors keyed on that convention keep resolving.
+  // Trails the label rather than leading it, so the label itself sits flush left with no reserved
+  // gutter.
+  action?: { label: string; onClick: () => void };
+  // This group's individual items, already anchored (the same anchors a caller's search feature
+  // would scroll to) — shown nested/indented when the row's chevron is expanded. Absent (not
+  // empty) means "no chevron for this row" — real navigation, not a filter group with members to
+  // list.
+  children?: SidebarLeafRow[];
+  // A row can opt into starting expanded rather than collapsed, e.g. a section's sole "Ungrouped"
+  // row that should stay always-visible.
+  defaultExpanded?: boolean;
+}

package/speech-registry.svelte.ts

@@ -0,0 +1,50 @@
+// The one shared "who's currently speaking" registry, mirroring menu-registry.svelte.ts's
+// singleton shape: starting a new utterance stops whatever else was speaking, and clicking the
+// currently-speaking bubble's own button again stops it (toggle) — the same "only one thing
+// active" convention a popover-heavy UI wants for this too.
+//
+// speechSynthesis is a real, global, OS-level engine — it can finish an utterance (or fail) entirely
+// on its own, not just via a manual stop() call. `onend`/`onerror` on the utterance are what keep
+// `speakingId` in sync with reality in that case; a plain isSpeaking() flag flipped only at the two
+// call sites (speak/stop) would go stale the instant a normal utterance finishes.
+const state = $state<{ speakingId: string | null }>({ speakingId: null });
+
+function synth(): SpeechSynthesis | undefined {
+  return typeof window !== "undefined" ? window.speechSynthesis : undefined;
+}
+
+export function isSpeechSupported(): boolean {
+  return !!synth();
+}
+
+export const speechRegistry = {
+  isSpeaking(id: string): boolean {
+    return state.speakingId === id;
+  },
+  speak(id: string, text: string): void {
+    const s = synth();
+    if (!s || !text.trim()) return;
+    // cancel()'s `end` event is dispatched as its own task, never inside this call — which is what
+    // makes the toggle below reachable, since it compares against a speakingId this cancel has not
+    // had the chance to clear. The old speakingId is cleared by the assignment further down (or by
+    // the toggle); each handler guards on its own id so a late `end` cannot clear a newer utterance.
+    // (An earlier version of this comment claimed the opposite, that cancel() fires onend
+    // SYNCHRONOUSLY and that this is what clears the old id. Were that true the toggle would be
+    // dead code and a second click would re-speak.)
+    s.cancel();
+    if (state.speakingId === id) {
+      // Toggle: clicking the already-speaking bubble's own button again just stops it.
+      state.speakingId = null;
+      return;
+    }
+    const utterance = new SpeechSynthesisUtterance(text);
+    utterance.onend = () => { if (state.speakingId === id) state.speakingId = null; };
+    utterance.onerror = () => { if (state.speakingId === id) state.speakingId = null; };
+    state.speakingId = id;
+    s.speak(utterance);
+  },
+  stop(): void {
+    synth()?.cancel();
+    state.speakingId = null;
+  },
+};

package/theme.css

@@ -0,0 +1,94 @@
+/* Shell + persona theme: the design tokens and cross-cutting CSS every app built on frame needs,
+   not tied to any one component. Import once (e.g. from the host app's entry point) alongside the
+   app's own stylesheet. Persona tokens name provenance generically — assistant/owner/provider —
+   so a non-health app can reuse the same three-way attribution bubble without health vocabulary. */
+:root {
+  --bg: #fafaf9;
+  --fg: #1a1a1a;
+  --muted: #6b7280;
+  --border: #e5e7eb;
+  --accent: #0b6bcb;
+  /* Neutral surfaces distinct from --bg, used for cards/panels raised above the page. */
+  --surface: #fff;
+  --surface-2: #f4f4f5;
+  --panel: #fbfcfd;
+  --code-bg: #f4f6f8;
+  --tt-footer-accent: var(--accent);
+  --band: rgba(11, 107, 203, 0.08);
+  --safe: #16a34a;
+  --safe-band: rgba(22, 163, 74, 0.10);
+  --warn: #d97706;
+  --warn-band: rgba(217, 119, 6, 0.10);
+  --alert: #dc2626;
+  --alert-band: rgba(220, 38, 38, 0.10);
+  /* "Generated" content — extracted from a source or produced by the AI. */
+  --gen: #7c5cbf;
+  --gen-band: rgba(124, 92, 191, 0.10);
+  --content-max: 76rem;
+  --leaf-max: 44rem;
+  /* Persona provenance: who produced a piece of content. */
+  --p-assistant: var(--gen);
+  --p-assistant-band: var(--gen-band);
+  --p-owner: #2f6f4f;
+  --p-owner-band: rgba(47, 111, 79, 0.10);
+  --p-provider: #64748b;
+  --p-provider-band: rgba(100, 116, 139, 0.12);
+}
+
+/* The standard visually-hidden recipe: removed from view but kept in the accessibility tree.
+   display:none and visibility:hidden would remove it from BOTH, which defeats the purpose. */
+.sr-only {
+  position: absolute;
+  width: 1px; height: 1px;
+  padding: 0; margin: -1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+
+/* Shared shell so the footer/disclaimer render on every state (lock/roster/app); sticky footer. */
+.app-shell { display: flex; flex-direction: column; min-height: 100dvh; }
+.app-body { flex: 1 0 auto; }
+
+/* Transient highlight applied when a permalink resolves, so the target is obvious after the
+   scroll. Plain (not scoped) CSS: it lands on arbitrary anchored elements anywhere. */
+.permalink-flash {
+  animation: permalink-flash 1.2s ease-out;
+  border-radius: 6px;
+}
+@keyframes permalink-flash {
+  0% { box-shadow: 0 0 0 3px var(--accent); background: var(--band); }
+  100% { box-shadow: 0 0 0 3px color-mix(in srgb, var(--accent) 0%, transparent); background: transparent; }
+}
+
+/* Shared field+action row: every field's own label stays a column (label text above, control
+   below); this wraps just the control + a side action (e.g. a mic button) side by side. */
+.field-row { display: flex; align-items: flex-start; gap: 0.35rem; }
+.field-row input, .field-row textarea { flex: 1; min-width: 0; }
+
+/* The section shell every top-level view repeats, several combined with a dynamic domain class.
+   Plain class, not a component: usage is too dynamic to earn a prop API and moving just the CSS
+   already gets the shared-source-of-truth goal. */
+.leaf-section { max-width: var(--leaf-max); margin: 0 auto; }
+
+/* Same class name, same body, wherever a leaf editor takes a single free-text topic line. */
+.topic-input { font: inherit; font-size: 0.95rem; color: var(--fg); padding: 0.5rem 0.65rem; border: 1px solid var(--border); border-radius: 6px; background: white; width: 100%; box-sizing: border-box; }
+
+/* Shared persona bubble: a tinted box with a head row (uppercase tag on the left, an optional
+   meta/date + action on the right). PersonaBubble.svelte is the sole production emitter. */
+.persona-bubble { border: 1px solid var(--border); border-radius: 12px; padding: 0.55rem 0.7rem; background: var(--surface); }
+.persona-head { display: flex; align-items: center; justify-content: space-between; gap: 0.5rem; margin-bottom: 0.4rem; }
+.persona-head-left { display: inline-flex; align-items: center; gap: 0.35rem; }
+.persona-head-right { display: inline-flex; align-items: center; gap: 0.4rem; }
+.persona-tag {
+  display: inline-block; font-size: 0.6rem; font-weight: 700; text-transform: uppercase; letter-spacing: 0.07em;
+  border: 1px solid; border-radius: 999px; padding: 0.05rem 0.45rem; background: var(--surface);
+}
+.persona-meta { font-size: 0.72rem; color: var(--muted); font-variant-numeric: tabular-nums; white-space: nowrap; }
+.p-assistant { background: var(--p-assistant-band); border-color: var(--p-assistant); }
+.p-assistant .persona-tag { color: var(--p-assistant); border-color: var(--p-assistant); }
+.p-owner { background: var(--p-owner-band); border-color: var(--p-owner); }
+.p-owner .persona-tag { color: var(--p-owner); border-color: var(--p-owner); }
+.p-provider { background: var(--p-provider-band); border-color: var(--p-provider); }
+.p-provider .persona-tag { color: var(--p-provider); border-color: var(--p-provider); }

package/time-ago.test.ts

@@ -0,0 +1,32 @@
+import { describe, it, expect } from "vitest";
+import { timeAgo } from "./time-ago";
+
+describe("timeAgo", () => {
+  const NOW = new Date("2026-07-05T12:00:00Z").getTime();
+  const ago = (ms: number) => new Date(NOW - ms).toISOString();
+  const s = 1000, m = 60 * s, h = 60 * m, d = 24 * h;
+
+  it("collapses the last few seconds to 'just now'", () => {
+    expect(timeAgo(ago(5 * s), NOW)).toBe("just now");
+    expect(timeAgo(ago(44 * s), NOW)).toBe("just now");
+  });
+
+  it("reports minutes, hours, and days with correct pluralization", () => {
+    expect(timeAgo(ago(1 * m), NOW)).toBe("1 minute ago");
+    expect(timeAgo(ago(5 * m), NOW)).toBe("5 minutes ago");
+    expect(timeAgo(ago(1 * h), NOW)).toBe("1 hour ago");
+    expect(timeAgo(ago(3 * h), NOW)).toBe("3 hours ago");
+    expect(timeAgo(ago(1 * d), NOW)).toBe("1 day ago");
+    expect(timeAgo(ago(2 * d), NOW)).toBe("2 days ago");
+  });
+
+  it("rolls up to months and years for older timestamps", () => {
+    expect(timeAgo(ago(45 * d), NOW)).toBe("2 months ago");
+    expect(timeAgo(ago(400 * d), NOW)).toBe("1 year ago");
+  });
+
+  it("degrades a future or malformed timestamp instead of throwing", () => {
+    expect(timeAgo(ago(-1 * h), NOW)).toBe("just now"); // clock skew → future
+    expect(timeAgo("not-a-date", NOW)).toBe("unknown");
+  });
+});

package/time-ago.ts

@@ -0,0 +1,18 @@
+// Relative "N hours/days ago" formatting. Pure: the caller passes `now` (ms) so it's
+// deterministic and unit-testable. A future/malformed timestamp degrades to "just now"/"unknown".
+export function timeAgo(iso: string, now: number): string {
+  const then = new Date(iso).getTime();
+  if (!Number.isFinite(then)) return "unknown";
+  const sec = Math.round((now - then) / 1000);
+  if (sec < 45) return "just now";
+  const min = Math.round(sec / 60);
+  if (min < 60) return `${min} minute${min === 1 ? "" : "s"} ago`;
+  const hr = Math.round(min / 60);
+  if (hr < 24) return `${hr} hour${hr === 1 ? "" : "s"} ago`;
+  const day = Math.round(hr / 24);
+  if (day < 30) return `${day} day${day === 1 ? "" : "s"} ago`;
+  const mon = Math.round(day / 30);
+  if (mon < 12) return `${mon} month${mon === 1 ? "" : "s"} ago`;
+  const yr = Math.round(mon / 12);
+  return `${yr} year${yr === 1 ? "" : "s"} ago`;
+}