npm - @markbrutx/promptbook-viewer - Versions diffs - 0.1.0 - Mend

@markbrutx/promptbook-viewer 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (76) hide show

package/LICENSE +21 -0
package/README.md +38 -0
package/dist/index.d.ts +6 -0
package/dist/index.d.ts.map +1 -0
package/dist/index.js +3 -0
package/dist/index.js.map +1 -0
package/dist/server/annotations.d.ts +30 -0
package/dist/server/annotations.d.ts.map +1 -0
package/dist/server/annotations.js +62 -0
package/dist/server/annotations.js.map +1 -0
package/dist/server/api.d.ts +16 -0
package/dist/server/api.d.ts.map +1 -0
package/dist/server/api.js +134 -0
package/dist/server/api.js.map +1 -0
package/dist/server/book-source.d.ts +20 -0
package/dist/server/book-source.d.ts.map +1 -0
package/dist/server/book-source.js +32 -0
package/dist/server/book-source.js.map +1 -0
package/dist/server/responses.d.ts +12 -0
package/dist/server/responses.d.ts.map +1 -0
package/dist/server/responses.js +106 -0
package/dist/server/responses.js.map +1 -0
package/dist/server/segments.d.ts +12 -0
package/dist/server/segments.d.ts.map +1 -0
package/dist/server/segments.js +24 -0
package/dist/server/segments.js.map +1 -0
package/dist/server/server.d.ts +24 -0
package/dist/server/server.d.ts.map +1 -0
package/dist/server/server.js +71 -0
package/dist/server/server.js.map +1 -0
package/dist/server/static.d.ts +8 -0
package/dist/server/static.d.ts.map +1 -0
package/dist/server/static.js +55 -0
package/dist/server/static.js.map +1 -0
package/dist/server/used-in.d.ts +9 -0
package/dist/server/used-in.d.ts.map +1 -0
package/dist/server/used-in.js +19 -0
package/dist/server/used-in.js.map +1 -0
package/dist/shared/types.d.ts +113 -0
package/dist/shared/types.d.ts.map +1 -0
package/dist/shared/types.js +2 -0
package/dist/shared/types.js.map +1 -0
package/dist/web/assets/index-B2Wxtb-f.css +1 -0
package/dist/web/assets/index-C8f_6lr_.js +51 -0
package/dist/web/index.html +13 -0
package/package.json +47 -0
package/src/index.ts +19 -0
package/src/server/annotations.ts +96 -0
package/src/server/api.ts +164 -0
package/src/server/book-source.ts +54 -0
package/src/server/responses.ts +127 -0
package/src/server/segments.ts +26 -0
package/src/server/server.ts +96 -0
package/src/server/static.ts +60 -0
package/src/server/used-in.ts +23 -0
package/src/shared/types.ts +137 -0
package/src/web/App.tsx +307 -0
package/src/web/annotations.ts +58 -0
package/src/web/api.ts +44 -0
package/src/web/colors.ts +21 -0
package/src/web/components/Addons.tsx +109 -0
package/src/web/components/Canvas.tsx +180 -0
package/src/web/components/CodePromptView.tsx +87 -0
package/src/web/components/Controls.tsx +71 -0
package/src/web/components/Diff.tsx +30 -0
package/src/web/components/FragmentView.tsx +54 -0
package/src/web/components/Sidebar.tsx +178 -0
package/src/web/diff.ts +51 -0
package/src/web/env.d.ts +3 -0
package/src/web/format.ts +8 -0
package/src/web/index.html +12 -0
package/src/web/main.tsx +15 -0
package/src/web/selection.ts +5 -0
package/src/web/styles.css +484 -0
package/src/web/tree.ts +134 -0
package/src/web/types.ts +17 -0

package/src/server/static.ts ADDED Viewed

@@ -0,0 +1,60 @@
+import { readFile, stat } from "node:fs/promises";
+import type { ServerResponse } from "node:http";
+import { extname, join, normalize } from "node:path";
+const MIME: Record<string, string> = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".ico": "image/x-icon",
+  ".woff2": "font/woff2",
+};
+/** Placeholder shown when the web bundle is missing (folder not built yet). */
+const NOT_BUILT = `<!doctype html><meta charset="utf-8"><title>promptbook viewer</title>
+<body style="font-family:system-ui;padding:2rem;line-height:1.5">
+<h1>promptbook viewer</h1>
+<p>The web bundle was not found. Build it with:</p>
+<pre>npm -w @markbrutx/promptbook-viewer run build</pre>
+<p>The API is live at <code>/api/book</code>.</p>`;
+/** Resolve a request path to a file inside the web root, blocking traversal. */
+function resolveAsset(webRoot: string, urlPath: string): string {
+  const clean = normalize(urlPath).replace(/^(\.\.[/\\])+/, "");
+  const rel = clean === "/" || clean === "" ? "index.html" : clean.replace(/^\/+/, "");
+  return join(webRoot, rel);
+}
+async function readIfFile(path: string): Promise<Buffer | undefined> {
+  try {
+    if ((await stat(path)).isFile()) {
+      return await readFile(path);
+    }
+  } catch {
+    // fall through
+  }
+  return undefined;
+}
+/**
+ * Serve a static asset from the built web bundle. Unknown paths fall back to
+ * `index.html` (single-page app), and a missing bundle yields a friendly page
+ * pointing at the build command rather than a bare 404.
+ */
+export async function serveStatic(res: ServerResponse, webRoot: string, urlPath: string): Promise<void> {
+  const asset = resolveAsset(webRoot, urlPath);
+  const direct = await readIfFile(asset);
+  if (direct !== undefined) {
+    res.writeHead(200, { "content-type": MIME[extname(asset)] ?? "application/octet-stream" });
+    res.end(direct);
+    return;
+  }
+  const index = await readIfFile(join(webRoot, "index.html"));
+  res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+  res.end(index ?? NOT_BUILT);
+}

package/src/server/used-in.ts ADDED Viewed

@@ -0,0 +1,23 @@
+import type { PromptBook } from "@markbrutx/promptbook-core";
+import { iterateReferences } from "@markbrutx/promptbook-core";
+import type { UsedInReference } from "../shared/types.js";
+/**
+ * All references to `fragmentId` across compositions (base/order + each rule's
+ * add/after/replace/forbid/order), reported per-composition for the used-in
+ * panel. Reuses core's reference walk so the viewer can't drift from lint.
+ */
+export function usedIn(book: PromptBook, fragmentId: string): UsedInReference[] {
+  const references: UsedInReference[] = [];
+  for (const ref of iterateReferences(book)) {
+    if (ref.id !== fragmentId) {
+      continue;
+    }
+    references.push(
+      ref.ruleIndex === undefined
+        ? { composition: ref.composition, role: ref.role }
+        : { composition: ref.composition, role: ref.role, ruleIndex: ref.ruleIndex },
+    );
+  }
+  return references;
+}

package/src/shared/types.ts ADDED Viewed

@@ -0,0 +1,137 @@
+/**
+ * Wire types shared by the server and the web app. These are the JSON shapes
+ * the `/api/*` routes speak; importing them on both sides keeps the contract
+ * in one place. Only type-only imports from `@markbrutx/promptbook-core` are used so the
+ * file carries no runtime dependency.
+ */
+import type {
+  Annotation,
+  Context,
+  FragmentReference,
+  LintFinding,
+  RuleAction,
+  Trace,
+  When,
+} from "@markbrutx/promptbook-core";
+export type { Annotation } from "@markbrutx/promptbook-core";
+/** A rule reduced to what the viewer renders (no behavior, just the shape). */
+export interface RuleSummary {
+  index: number;
+  when: When;
+  action: RuleAction;
+  add?: string[];
+  after?: string;
+  replace?: Record<string, string>;
+  forbid?: string[];
+  order?: string[];
+}
+/** A named context preset for a composition, sourced from `fixtures/`. */
+export interface VariantSummary {
+  name: string;
+  context: Context;
+}
+/** A composition as the sidebar/canvas needs it. */
+export interface CompositionSummary {
+  name: string;
+  base: string[];
+  order?: string[];
+  rules: RuleSummary[];
+  sourceFile: string;
+  variants: VariantSummary[];
+}
+/** A fragment as the inspector/used-in panels need it. */
+export interface FragmentSummary {
+  id: string;
+  kind?: string;
+  tags: string[];
+  body: string;
+  sourceFile: string;
+}
+/** One captured snapshot of a code-prompt's output (the builder is never run). */
+interface CodePromptSampleSummary {
+  label: string;
+  context?: Context;
+  output: string;
+}
+/** A builder-backed prompt as the unified menu/canvas needs it. */
+export interface CodePromptSummary {
+  name: string;
+  description?: string;
+  samples: CodePromptSampleSummary[];
+  sourceFile: string;
+}
+/** Response of `GET /api/book`. */
+export interface BookResponse {
+  compositions: CompositionSummary[];
+  codePrompts: CodePromptSummary[];
+  fragments: FragmentSummary[];
+  warnings: string[];
+}
+/** One colored slice of the assembled prompt, mapped to its source fragment. */
+export interface Segment {
+  fragmentId: string;
+  text: string;
+}
+/** Request body for `POST /api/resolve` and `POST /api/lint`. */
+export interface ResolveRequest {
+  prompt: string;
+  context?: Context;
+}
+/** Response of `POST /api/resolve`. */
+export interface ResolveResponse {
+  text: string;
+  trace: Trace;
+  segments: Segment[];
+}
+/** Response of `POST /api/lint`. */
+export interface LintResponse {
+  findings: LintFinding[];
+  errorCount: number;
+  warningCount: number;
+  tokens: number;
+}
+/** Where a fragment id is referenced inside a composition (core's role union). */
+type UsedInRole = FragmentReference["role"];
+/** One reference to a fragment, as `GET /api/used-in/:id` reports it. */
+export interface UsedInReference {
+  composition: string;
+  role: UsedInRole;
+  ruleIndex?: number;
+}
+/** Response of `GET /api/used-in/:id`. */
+export interface UsedInResponse {
+  fragmentId: string;
+  references: UsedInReference[];
+}
+/** Request body for `POST /api/annotate`. */
+export interface AnnotateRequest {
+  /** Composition of the annotated variant (omit when targeting a fragment). */
+  prompt?: string;
+  context?: Context;
+  fragmentId: string;
+  anchorText: string;
+  comment: string;
+  offset?: number;
+  sourceFile?: string;
+}
+/** Response of `GET /api/annotations`. */
+export interface AnnotationsResponse {
+  annotations: Annotation[];
+}

package/src/web/App.tsx ADDED Viewed

@@ -0,0 +1,307 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { api } from "./api.js";
+import { Addons } from "./components/Addons.js";
+import { Canvas } from "./components/Canvas.js";
+import { CodePromptView } from "./components/CodePromptView.js";
+import { Controls } from "./components/Controls.js";
+import { Diff } from "./components/Diff.js";
+import { FragmentView } from "./components/FragmentView.js";
+import { Sidebar } from "./components/Sidebar.js";
+import type { Selection } from "./selection.js";
+import { buildCompositionTree, buildFragmentGroups, DEFAULT_VARIANT } from "./tree.js";
+import type {
+  Annotation,
+  BookResponse,
+  CompositionSummary,
+  Context,
+  LintResponse,
+  ResolveResponse,
+  UsedInResponse,
+} from "./types.js";
+/** Order-independent key for comparing two contexts (variant identity). */
+function contextKey(context: Context): string {
+  return JSON.stringify(Object.entries(context).sort(([a], [b]) => a.localeCompare(b)));
+}
+/** The context a named variant carries (Default = empty). */
+function variantContext(composition: CompositionSummary | undefined, variant: string): Context {
+  if (composition === undefined || variant === DEFAULT_VARIANT.name) {
+    return {};
+  }
+  return composition.variants.find((v) => v.name === variant)?.context ?? {};
+}
+/** The context axes worth offering as Controls for a composition. */
+function controlKeys(composition: CompositionSummary | undefined): string[] {
+  if (composition === undefined) {
+    return [];
+  }
+  const keys = new Set<string>();
+  for (const rule of composition.rules) {
+    for (const key of Object.keys(rule.when)) {
+      keys.add(key);
+    }
+  }
+  return [...keys];
+}
+export function App() {
+  const [book, setBook] = useState<BookResponse | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [selection, setSelection] = useState<Selection | null>(null);
+  const [context, setContext] = useState<Context>({});
+  const [resolved, setResolved] = useState<ResolveResponse | null>(null);
+  const [lint, setLint] = useState<LintResponse | null>(null);
+  const [usedIn, setUsedIn] = useState<UsedInResponse | null>(null);
+  const [compareVariant, setCompareVariant] = useState<string>("");
+  const [compareResolved, setCompareResolved] = useState<ResolveResponse | null>(null);
+  const [annotations, setAnnotations] = useState<Annotation[]>([]);
+  const requestId = useRef(0);
+  const loadAnnotations = useCallback(async () => {
+    try {
+      const { annotations: next } = await api.annotations();
+      setAnnotations(next);
+    } catch {
+      setAnnotations([]);
+    }
+  }, []);
+  const loadBook = useCallback(async () => {
+    try {
+      const next = await api.book();
+      setBook(next);
+      setError(null);
+      return next;
+    } catch (e) {
+      setError((e as Error).message);
+      return null;
+    }
+  }, []);
+  // Initial load + pick the first composition's Default variant.
+  useEffect(() => {
+    void loadBook().then((next) => {
+      const first = next?.compositions[0];
+      if (first !== undefined) {
+        setSelection({ kind: "variant", composition: first.name, variant: DEFAULT_VARIANT.name });
+        setContext({});
+      }
+    });
+    void loadAnnotations();
+  }, [loadBook, loadAnnotations]);
+  // Hot-reload: refetch the book on folder changes. The new book object is a
+  // fresh reference, so the resolve/used-in effects below re-run automatically.
+  useEffect(() => {
+    const source = new EventSource("/api/events");
+    source.addEventListener("reload", () => void loadBook());
+    return () => source.close();
+  }, [loadBook]);
+  const compositions = book?.compositions ?? [];
+  const selectedComposition =
+    selection?.kind === "variant" ? compositions.find((c) => c.name === selection.composition) : undefined;
+  useEffect(() => {
+    if (book === null || selection?.kind !== "variant") {
+      setResolved(null);
+      setLint(null);
+      return;
+    }
+    requestId.current += 1;
+    const id = requestId.current;
+    const { composition } = selection;
+    void Promise.all([api.resolve(composition, context), api.lint(composition, context)])
+      .then(([r, l]) => {
+        if (requestId.current === id) {
+          setResolved(r);
+          setLint(l);
+          setError(null);
+        }
+      })
+      .catch((e) => {
+        if (requestId.current === id) {
+          setError((e as Error).message);
+        }
+      });
+  }, [book, selection, context]);
+  useEffect(() => {
+    if (book === null || selection?.kind !== "fragment") {
+      setUsedIn(null);
+      return;
+    }
+    void api
+      .usedIn(selection.id)
+      .then(setUsedIn)
+      .catch(() => setUsedIn(null));
+  }, [book, selection]);
+  // Resolve the comparison variant for the Diff panel.
+  useEffect(() => {
+    if (selection?.kind !== "variant" || compareVariant === "") {
+      setCompareResolved(null);
+      return;
+    }
+    const ctx = variantContext(selectedComposition, compareVariant);
+    void api
+      .resolve(selection.composition, ctx)
+      .then(setCompareResolved)
+      .catch(() => setCompareResolved(null));
+  }, [selection, compareVariant, selectedComposition]);
+  const selectVariant = useCallback(
+    (composition: string, variant: string) => {
+      const summary = compositions.find((c) => c.name === composition);
+      setSelection({ kind: "variant", composition, variant });
+      setContext(variantContext(summary, variant));
+      setCompareVariant("");
+    },
+    [compositions],
+  );
+  const selectCode = useCallback((name: string, sample: string) => {
+    setSelection({ kind: "code", name, sample });
+  }, []);
+  const selectFragment = useCallback((id: string) => {
+    setSelection({ kind: "fragment", id });
+  }, []);
+  const addAnnotation = useCallback(
+    async (fragmentId: string, anchorText: string, comment: string) => {
+      if (selection?.kind !== "variant") {
+        return;
+      }
+      await api.annotate({ prompt: selection.composition, context, fragmentId, anchorText, comment });
+      await loadAnnotations();
+    },
+    [selection, context, loadAnnotations],
+  );
+  const resolveAnnotation = useCallback(
+    async (id: string) => {
+      await api.resolveAnnotation(id);
+      await loadAnnotations();
+    },
+    [loadAnnotations],
+  );
+  // Annotations belonging to exactly the variant on screen (composition + context).
+  const variantAnnotations = useMemo(() => {
+    if (selection?.kind !== "variant") {
+      return [];
+    }
+    const key = contextKey(context);
+    return annotations.filter(
+      (a) => a.target.prompt === selection.composition && contextKey(a.target.context ?? {}) === key,
+    );
+  }, [annotations, selection, context]);
+  const codePrompts = book?.codePrompts ?? [];
+  const tree = useMemo(() => buildCompositionTree(compositions, codePrompts), [compositions, codePrompts]);
+  const fragmentGroups = useMemo(() => buildFragmentGroups(book?.fragments ?? []), [book]);
+  const selectedFragment =
+    selection?.kind === "fragment" ? book?.fragments.find((f) => f.id === selection.id) : undefined;
+  const selectedCodePrompt =
+    selection?.kind === "code" ? codePrompts.find((c) => c.name === selection.name) : undefined;
+  return (
+    <div className="layout">
+      <Sidebar
+        tree={tree}
+        fragmentGroups={fragmentGroups}
+        selection={selection}
+        onSelectVariant={selectVariant}
+        onSelectCode={selectCode}
+        onSelectFragment={selectFragment}
+      />
+      {error !== null ? (
+        <main className="canvas">
+          <p className="warn">{error}</p>
+        </main>
+      ) : null}
+      {error === null && selection?.kind === "variant" && resolved !== null ? (
+        <Canvas
+          title={selection.composition}
+          subtitle={selection.variant}
+          segments={resolved.segments}
+          tokens={lint?.tokens}
+          annotations={variantAnnotations}
+          onAnnotate={addAnnotation}
+        />
+      ) : null}
+      {error === null && selection?.kind === "code" && selectedCodePrompt !== undefined ? (
+        <CodePromptView
+          codePrompt={selectedCodePrompt}
+          sample={selection.sample}
+          onSelectSample={(label) => selectCode(selectedCodePrompt.name, label)}
+        />
+      ) : null}
+      {error === null && selectedFragment !== undefined ? (
+        <FragmentView
+          fragment={selectedFragment}
+          usedIn={usedIn}
+          onSelectVariant={(composition) => selectVariant(composition, DEFAULT_VARIANT.name)}
+        />
+      ) : null}
+      {selection?.kind === "variant" && resolved !== null ? (
+        <aside className="rail">
+          <section>
+            <h3>Controls</h3>
+            <Controls keys={controlKeys(selectedComposition)} context={context} onChange={setContext} />
+          </section>
+          <section>
+            <h3>Diff</h3>
+            <select value={compareVariant} onChange={(event) => setCompareVariant(event.target.value)}>
+              <option value="">Compare with…</option>
+              <option value={DEFAULT_VARIANT.name}>{DEFAULT_VARIANT.name}</option>
+              {(selectedComposition?.variants ?? []).map((variant) => (
+                <option key={variant.name} value={variant.name}>
+                  {variant.name}
+                </option>
+              ))}
+            </select>
+            {compareResolved !== null ? (
+              <Diff
+                leftLabel={compareVariant}
+                rightLabel={selection.variant}
+                leftText={compareResolved.text}
+                rightText={resolved.text}
+              />
+            ) : null}
+          </section>
+          <section>
+            <h3>Annotations</h3>
+            {variantAnnotations.length === 0 ? (
+              <p className="muted">None yet. Select text in the prompt to leave a comment for the agent.</p>
+            ) : (
+              <ul className="annot-list">
+                {variantAnnotations.map((a) => (
+                  <li key={a.id}>
+                    <p className="annot-quote">“{a.anchor.anchorText}”</p>
+                    <p className="annot-comment">{a.comment}</p>
+                    <div className="annot-meta">
+                      <code className="muted">{a.anchor.fragmentId}</code>
+                      <button type="button" className="link" onClick={() => void resolveAnnotation(a.id)}>
+                        Resolve
+                      </button>
+                    </div>
+                  </li>
+                ))}
+              </ul>
+            )}
+          </section>
+          <Addons trace={resolved.trace} lint={lint} />
+        </aside>
+      ) : null}
+    </div>
+  );
+}

package/src/web/annotations.ts ADDED Viewed

@@ -0,0 +1,58 @@
+/** One run of a segment's text; `annotationId` marks an annotated span. */
+export interface TextRun {
+  text: string;
+  annotationId?: string;
+}
+/** An existing annotation's anchor, reduced to what highlighting needs. */
+export interface AnchorSpec {
+  id: string;
+  anchorText: string;
+}
+/**
+ * Split `text` into runs, marking the first non-overlapping occurrence of each
+ * anchor. Used to highlight existing annotations inside a colored segment.
+ * Pure and DOM-free so it is unit-tested directly.
+ */
+export function markAnchors(text: string, anchors: AnchorSpec[]): TextRun[] {
+  interface Range {
+    start: number;
+    end: number;
+    id: string;
+  }
+  const ranges: Range[] = [];
+  for (const anchor of anchors) {
+    if (anchor.anchorText === "") {
+      continue;
+    }
+    let from = 0;
+    while (from <= text.length) {
+      const start = text.indexOf(anchor.anchorText, from);
+      if (start === -1) {
+        break;
+      }
+      const end = start + anchor.anchorText.length;
+      if (!ranges.some((r) => start < r.end && end > r.start)) {
+        ranges.push({ start, end, id: anchor.id });
+        break;
+      }
+      from = start + 1;
+    }
+  }
+  ranges.sort((a, b) => a.start - b.start);
+  const runs: TextRun[] = [];
+  let cursor = 0;
+  for (const range of ranges) {
+    if (range.start > cursor) {
+      runs.push({ text: text.slice(cursor, range.start) });
+    }
+    runs.push({ text: text.slice(range.start, range.end), annotationId: range.id });
+    cursor = range.end;
+  }
+  if (cursor < text.length || runs.length === 0) {
+    runs.push({ text: text.slice(cursor) });
+  }
+  return runs;
+}

package/src/web/api.ts ADDED Viewed

@@ -0,0 +1,44 @@
+import type {
+  AnnotateRequest,
+  Annotation,
+  AnnotationsResponse,
+  BookResponse,
+  Context,
+  LintResponse,
+  ResolveResponse,
+  UsedInResponse,
+} from "./types.js";
+async function getJson<T>(path: string): Promise<T> {
+  const res = await fetch(path);
+  if (!res.ok) {
+    throw new Error(`${path} → ${res.status}`);
+  }
+  return (await res.json()) as T;
+}
+async function sendJson<T>(method: "POST" | "DELETE", path: string, body?: unknown): Promise<T> {
+  const res = await fetch(path, {
+    method,
+    headers: { "content-type": "application/json" },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  if (!res.ok) {
+    const payload = (await res.json().catch(() => ({}))) as { error?: string };
+    throw new Error(payload.error ?? `${path} → ${res.status}`);
+  }
+  return (await res.json()) as T;
+}
+export const api = {
+  book: () => getJson<BookResponse>("/api/book"),
+  resolve: (prompt: string, context: Context) =>
+    sendJson<ResolveResponse>("POST", "/api/resolve", { prompt, context }),
+  lint: (prompt: string, context: Context) =>
+    sendJson<LintResponse>("POST", "/api/lint", { prompt, context }),
+  usedIn: (fragmentId: string) => getJson<UsedInResponse>(`/api/used-in/${encodeURIComponent(fragmentId)}`),
+  annotations: () => getJson<AnnotationsResponse>("/api/annotations"),
+  annotate: (body: AnnotateRequest) => sendJson<Annotation>("POST", "/api/annotate", body),
+  resolveAnnotation: (id: string) =>
+    sendJson<{ id: string; removed: boolean }>("DELETE", `/api/annotations/${encodeURIComponent(id)}`),
+};

package/src/web/colors.ts ADDED Viewed

@@ -0,0 +1,21 @@
+/**
+ * Stable hue per fragment id, so a fragment keeps the same color across the
+ * canvas, sidebar and legend. Deterministic and dependency-free.
+ */
+function hueOf(id: string): number {
+  let hash = 0;
+  for (let i = 0; i < id.length; i += 1) {
+    hash = (hash * 31 + id.charCodeAt(i)) % 360;
+  }
+  return (hash + 360) % 360;
+}
+/** Soft background tint for a fragment's segment. */
+export function fragmentColor(id: string): string {
+  return `hsl(${hueOf(id)}deg 70% 88%)`;
+}
+/** Saturated variant of {@link fragmentColor} for borders/legend swatches. */
+export function fragmentAccent(id: string): string {
+  return `hsl(${hueOf(id)}deg 60% 45%)`;
+}