@kitn.ai/ui 0.14.1

package/src/primitives/controllable.ts

@@ -0,0 +1,21 @@
+import { createSignal, type Accessor } from 'solid-js';
+
+/**
+ * The controlled/uncontrolled state pattern, as a reusable signal.
+ *
+ * `controlled` is an accessor for the controlling prop: when it returns a value,
+ * that value wins (controlled mode); when it returns `undefined`, the component
+ * manages its own state seeded from `initial` (uncontrolled mode). The returned
+ * setter always writes the internal value — harmless (masked) while controlled,
+ * authoritative while uncontrolled — so a single call site works in both modes.
+ *
+ * Mirrors `props.value ?? internal()` used elsewhere in the kit, without effects.
+ */
+export function createControllableSignal(
+  controlled: Accessor<boolean | undefined>,
+  initial: boolean,
+): [Accessor<boolean>, (value: boolean) => void] {
+  const [internal, setInternal] = createSignal(initial);
+  const value: Accessor<boolean> = () => controlled() ?? internal();
+  return [value, (v: boolean) => setInternal(v)];
+}

package/src/primitives/embed-providers.ts

@@ -0,0 +1,254 @@
+// src/primitives/embed-providers.ts
+// Pure provider resolution for <kai-embed>: map an EmbedCardData → an embeddable
+// player URL + poster + iframe sandbox/allow. Covers youtube (privacy-enhanced
+// youtube-nocookie), vimeo (dnt=1), and generic (https-only, ORIGIN-ALLOWLISTED).
+// No network, no DOM. See docs/superpowers/specs/2026-06-13-kc-link-embed-cards-design.md.
+import type { CardEnvelope } from './card-contract';
+
+/** Media provider for an embed card. */
+export type EmbedProvider = 'youtube' | 'vimeo' | 'generic';
+
+/** Lazy media-embed payload (YouTube / Vimeo / generic player URL). */
+export interface EmbedCardData {
+  /** Media provider. 'generic' frames `url` directly. */
+  provider: EmbedProvider;
+  /** Provider video id (youtube/vimeo) when not parsing from `url`. */
+  id?: string;
+  /** Full media/watch/embed URL. */
+  url?: string;
+  /** Accessible iframe title + poster label. */
+  title?: string;
+  /** Thumbnail before play; derived for youtube/vimeo when omitted. */
+  poster?: string;
+  /** Start offset, seconds. */
+  start?: number;
+  /** Player aspect ratio. Default '16:9'. */
+  aspectRatio?: '16:9' | '4:3' | '1:1' | '9:16';
+}
+
+/** The full envelope an agent/server emits for an embed card. */
+export type EmbedCardEnvelope = CardEnvelope<'embed', EmbedCardData>;
+
+/** The `type` discriminator for embed cards. */
+export const EMBED_CARD_TYPE = 'embed' as const;
+
+export interface ResolvedEmbed {
+  /** The iframe src loaded on play (already including autoplay/start params). */
+  embedUrl: string;
+  /** Poster/thumbnail to show before play (derived when not supplied). */
+  posterUrl?: string;
+  /** sandbox attribute for the player iframe. */
+  sandbox: string;
+  /** allow attribute (fullscreen, encrypted-media, picture-in-picture, …). */
+  allow: string;
+}
+
+// A provider player NEEDS allow-scripts + allow-same-origin (its OWN origin) to run.
+// That is safe here because the framed origin is a KNOWN, trusted video provider on a
+// DIFFERENT origin than the host — same-origin policy still isolates the host page from
+// the provider. allow-popups(-to-escape-sandbox) lets "watch on YouTube" work. The
+// `allow` attribute (not sandbox) governs autoplay/fullscreen/encrypted-media.
+// Contrast <kai-artifact> (allow-scripts allow-forms, NO allow-same-origin) which frames
+// arbitrary consumer HTML and so trusts nothing.
+const PLAYER_SANDBOX =
+  'allow-scripts allow-same-origin allow-presentation allow-popups allow-popups-to-escape-sandbox';
+const PLAYER_ALLOW =
+  'accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; fullscreen';
+
+// --- generic origin allowlist (security decision) -------------------------
+//
+// A `generic` embed frames an ARBITRARY https URL. An agent-supplied generic URL is a
+// supply-chain risk, so it is REJECTED unless the app has explicitly allowlisted its
+// origin. The allowlist defaults to EMPTY: out of the box, `generic` embeds are blocked.
+const allowedGenericOrigins = new Set<string>();
+
+/**
+ * App opt-in: allow `generic` embeds whose origin is in this list. Origins are
+ * normalized via the URL parser (scheme + host + port). Only https origins are
+ * accepted (a non-https origin is ignored). Call once at app startup.
+ */
+export function configureEmbedAllowlist(origins: string[]): void {
+  for (const o of origins) {
+    const origin = normalizeOrigin(o);
+    if (origin) allowedGenericOrigins.add(origin);
+  }
+}
+
+/** True when `url`'s origin has been allowlisted for `generic` embeds. */
+export function isGenericOriginAllowed(url: string): boolean {
+  const origin = originOf(url);
+  return origin !== undefined && allowedGenericOrigins.has(origin);
+}
+
+/** Test-only: clear the generic allowlist so tests stay isolated. */
+export function __resetEmbedAllowlistForTests(): void {
+  allowedGenericOrigins.clear();
+}
+
+/** Normalize an allowlist entry (a URL or bare origin) to a canonical https origin, or undefined. */
+function normalizeOrigin(input: string): string | undefined {
+  const origin = originOf(input) ?? originOf(`https://${input}`);
+  if (!origin) return undefined;
+  return origin.startsWith('https://') ? origin : undefined;
+}
+
+/** The `scheme://host[:port]` origin of a URL, or undefined when unparseable. */
+function originOf(url: string): string | undefined {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return undefined;
+  }
+}
+
+// --- id parsing -----------------------------------------------------------
+
+/** Extract a YouTube id from a watch / youtu.be / shorts / embed URL. */
+export function parseYouTubeId(url: string): string | undefined {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return undefined;
+  }
+  const host = parsed.hostname.replace(/^www\./, '');
+  if (host === 'youtu.be') {
+    return cleanId(parsed.pathname.slice(1));
+  }
+  if (host === 'youtube.com' || host === 'm.youtube.com' || host === 'youtube-nocookie.com') {
+    const v = parsed.searchParams.get('v');
+    if (v) return cleanId(v);
+    // /shorts/<id>, /embed/<id>, /v/<id>
+    const m = parsed.pathname.match(/^\/(?:shorts|embed|v)\/([^/?#]+)/);
+    if (m) return cleanId(m[1]);
+  }
+  return undefined;
+}
+
+/** Extract a Vimeo id from a vimeo.com/<id> (or player.vimeo.com/video/<id>) URL. */
+export function parseVimeoId(url: string): string | undefined {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return undefined;
+  }
+  const host = parsed.hostname.replace(/^www\./, '');
+  if (host !== 'vimeo.com' && host !== 'player.vimeo.com') return undefined;
+  const m = parsed.pathname.match(/(?:^|\/)(\d+)(?:\/|$)/);
+  return m ? m[1] : undefined;
+}
+
+/** A provider video id must be the [A-Za-z0-9_-] alphabet (matches the schema pattern). */
+function cleanId(id: string): string | undefined {
+  return /^[A-Za-z0-9_-]+$/.test(id) ? id : undefined;
+}
+
+// --- resolution -----------------------------------------------------------
+
+/**
+ * Resolve an EmbedCardData to an embeddable player URL + poster + sandbox/allow.
+ * Throws (with a human message) on a missing/invalid provider id, a non-https
+ * generic URL, or a generic origin not in the app allowlist — the card turns these
+ * into an inline error + an `error` event.
+ */
+export function resolveEmbed(data: EmbedCardData): ResolvedEmbed {
+  const start = data.start ? `&start=${data.start}` : '';
+  switch (data.provider) {
+    case 'youtube': {
+      const id = data.id ?? (data.url ? parseYouTubeId(data.url) : undefined);
+      if (!id) throw new Error('youtube embed: missing or unparseable id/url');
+      return {
+        embedUrl: `https://www.youtube-nocookie.com/embed/${id}?autoplay=1&rel=0${start}`,
+        posterUrl: data.poster ?? `https://i.ytimg.com/vi/${id}/hqdefault.jpg`,
+        sandbox: PLAYER_SANDBOX,
+        allow: PLAYER_ALLOW,
+      };
+    }
+    case 'vimeo': {
+      const id = data.id ?? (data.url ? parseVimeoId(data.url) : undefined);
+      if (!id) throw new Error('vimeo embed: missing or unparseable id/url');
+      return {
+        embedUrl: `https://player.vimeo.com/video/${id}?autoplay=1&dnt=1${
+          data.start ? `#t=${data.start}s` : ''
+        }`,
+        // Vimeo has no static thumbnail URL; rely on a supplied poster (or placeholder).
+        posterUrl: data.poster,
+        sandbox: PLAYER_SANDBOX,
+        allow: PLAYER_ALLOW,
+      };
+    }
+    case 'generic': {
+      if (!data.url) throw new Error('generic embed: missing url');
+      assertHttpsEmbeddable(data.url);
+      if (!isGenericOriginAllowed(data.url)) {
+        throw new Error(
+          `generic embed: origin not allowlisted — call configureEmbedAllowlist([...]) to permit ${
+            originOf(data.url) ?? data.url
+          }`,
+        );
+      }
+      return { embedUrl: data.url, posterUrl: data.poster, sandbox: PLAYER_SANDBOX, allow: PLAYER_ALLOW };
+    }
+  }
+}
+
+/** Reject non-https or javascript:/data: player URLs (defense in depth). */
+function assertHttpsEmbeddable(url: string): void {
+  let protocol: string;
+  try {
+    protocol = new URL(url).protocol;
+  } catch {
+    throw new Error(`generic embed: invalid url "${url}"`);
+  }
+  if (protocol !== 'https:') {
+    throw new Error(`generic embed: only https player URLs are allowed (got ${protocol})`);
+  }
+}
+
+/**
+ * The canonical "watch on the provider" URL for the optional fallback affordance
+ * (emitted as `open`/target:'tab' when an embed is blocked). Returns `undefined`
+ * when there is nothing useful to link to.
+ */
+export function watchUrl(data: EmbedCardData): string | undefined {
+  switch (data.provider) {
+    case 'youtube': {
+      const id = data.id ?? (data.url ? parseYouTubeId(data.url) : undefined);
+      return id ? `https://www.youtube.com/watch?v=${id}` : data.url;
+    }
+    case 'vimeo': {
+      const id = data.id ?? (data.url ? parseVimeoId(data.url) : undefined);
+      return id ? `https://vimeo.com/${id}` : data.url;
+    }
+    case 'generic':
+      return data.url;
+  }
+}
+
+/** Human-readable provider label for the fallback affordance ("Open on YouTube"). */
+export function providerLabel(provider: EmbedProvider): string {
+  switch (provider) {
+    case 'youtube':
+      return 'YouTube';
+    case 'vimeo':
+      return 'Vimeo';
+    case 'generic':
+      return 'site';
+  }
+}
+
+/** CSS aspect-ratio value for a card's aspectRatio (default 16:9). */
+export function aspectRatioValue(aspectRatio: EmbedCardData['aspectRatio']): string {
+  switch (aspectRatio) {
+    case '4:3':
+      return '4 / 3';
+    case '1:1':
+      return '1 / 1';
+    case '9:16':
+      return '9 / 16';
+    case '16:9':
+    default:
+      return '16 / 9';
+  }
+}

package/src/primitives/highlighter.ts

@@ -0,0 +1,157 @@
+// On-demand code highlighter built on Shiki's fine-grained core.
+//
+// Nothing here loads until `highlight()` is first called with highlighting
+// enabled — so a component set that never renders a code block ships and runs
+// with ZERO Shiki bytes. When a code block does appear, only the core, the
+// JavaScript regex engine (no WASM), the one theme, and the one language grammar
+// it needs are dynamically imported, each as its own small lazy chunk.
+//
+// Hosts extend or disable this via `configureCodeHighlighting()`.
+
+import type { HighlighterCore } from 'shiki/core';
+
+type Loader = () => Promise<unknown>;
+
+/**
+ * Minimal default language set — each a separate lazy chunk, loaded only on use.
+ * Kept deliberately small to keep the bundle lean; hosts add more at runtime via
+ * `configureCodeHighlighting({ languages })` (no rebuild needed — see that fn).
+ */
+const DEFAULT_LANGUAGES: Record<string, Loader> = {
+  bash: () => import('@shikijs/langs/bash'),
+  javascript: () => import('@shikijs/langs/javascript'),
+  typescript: () => import('@shikijs/langs/typescript'),
+  tsx: () => import('@shikijs/langs/tsx'),
+  html: () => import('@shikijs/langs/html'),
+  css: () => import('@shikijs/langs/css'),
+  json: () => import('@shikijs/langs/json'),
+  vue: () => import('@shikijs/langs/vue'),
+  svelte: () => import('@shikijs/langs/svelte'),
+};
+
+const DEFAULT_THEMES: Record<string, Loader> = {
+  'github-dark-dimmed': () => import('@shikijs/themes/github-dark-dimmed'),
+  'github-light': () => import('@shikijs/themes/github-light'),
+};
+
+const DEFAULT_ALIASES: Record<string, string> = {
+  js: 'javascript',
+  ts: 'typescript',
+  jsx: 'tsx',
+  sh: 'bash',
+  shell: 'bash',
+};
+
+const FALLBACK_THEME = 'github-dark-dimmed';
+
+export interface CodeHighlightingOptions {
+  /** Turn highlighting on/off globally. When false, code renders as plain text. */
+  enabled?: boolean;
+  /** Register/override language loaders, e.g. `{ ruby: () => import('@shikijs/langs/ruby') }`. */
+  languages?: Record<string, Loader>;
+  /** Register/override theme loaders. */
+  themes?: Record<string, Loader>;
+  /** Map short names to canonical language keys, e.g. `{ vue: 'html' }`. */
+  aliases?: Record<string, string>;
+}
+
+let enabled = true;
+let langLoaders: Record<string, Loader> = { ...DEFAULT_LANGUAGES };
+let themeLoaders: Record<string, Loader> = { ...DEFAULT_THEMES };
+let aliases: Record<string, string> = { ...DEFAULT_ALIASES };
+
+let highlighterPromise: Promise<HighlighterCore> | null = null;
+const loadedLangs = new Set<string>();
+const loadedThemes = new Set<string>();
+
+function getHighlighter(): Promise<HighlighterCore> {
+  if (!highlighterPromise) {
+    highlighterPromise = (async () => {
+      const [{ createHighlighterCore }, { createJavaScriptRegexEngine }] = await Promise.all([
+        import('shiki/core'),
+        import('shiki/engine/javascript'),
+      ]);
+      return createHighlighterCore({
+        themes: [],
+        langs: [],
+        engine: createJavaScriptRegexEngine(),
+      });
+    })();
+  }
+  return highlighterPromise;
+}
+
+function resolveLang(lang: string): string {
+  return aliases[lang] ?? lang;
+}
+
+async function ensureLang(hl: HighlighterCore, lang: string): Promise<boolean> {
+  const name = resolveLang(lang);
+  if (loadedLangs.has(name)) return true;
+  const loader = langLoaders[name];
+  if (!loader) return false;
+  await hl.loadLanguage(loader() as never);
+  loadedLangs.add(name);
+  return true;
+}
+
+async function ensureTheme(hl: HighlighterCore, theme: string): Promise<boolean> {
+  if (loadedThemes.has(theme)) return true;
+  const loader = themeLoaders[theme];
+  if (!loader) return false;
+  await hl.loadTheme(loader() as never);
+  loadedThemes.add(theme);
+  return true;
+}
+
+function escapeHtml(s: string): string {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+function plain(code: string): string {
+  return `<pre><code>${escapeHtml(code)}</code></pre>`;
+}
+
+/**
+ * Highlight `code` as `lang` with `theme`, returning HTML. Loads only what's
+ * needed, on demand. Falls back to escaped plain `<pre><code>` when highlighting
+ * is disabled, the language has no registered loader, or anything fails.
+ */
+export async function highlight(code: string, lang: string, theme: string): Promise<string> {
+  if (!enabled || !code) return plain(code);
+  try {
+    const hl = await getHighlighter();
+    const hasLang = await ensureLang(hl, lang);
+    if (!hasLang) return plain(code);
+    const useTheme = (await ensureTheme(hl, theme))
+      ? theme
+      : (await ensureTheme(hl, FALLBACK_THEME)) ? FALLBACK_THEME : null;
+    if (!useTheme) return plain(code);
+    return hl.codeToHtml(code, { lang: resolveLang(lang), theme: useTheme });
+  } catch {
+    return plain(code);
+  }
+}
+
+/** Register additional languages/themes/aliases, or disable highlighting entirely. */
+export function configureCodeHighlighting(options: CodeHighlightingOptions): void {
+  if (options.enabled !== undefined) enabled = options.enabled;
+  if (options.languages) langLoaders = { ...langLoaders, ...options.languages };
+  if (options.themes) themeLoaders = { ...themeLoaders, ...options.themes };
+  if (options.aliases) aliases = { ...aliases, ...options.aliases };
+}
+
+export function isCodeHighlightingEnabled(): boolean {
+  return enabled;
+}
+
+/** Test helper — reset the singleton and registries to defaults. */
+export function __resetCodeHighlightingForTests(): void {
+  enabled = true;
+  langLoaders = { ...DEFAULT_LANGUAGES };
+  themeLoaders = { ...DEFAULT_THEMES };
+  aliases = { ...DEFAULT_ALIASES };
+  highlighterPromise = null;
+  loadedLangs.clear();
+  loadedThemes.clear();
+}

package/src/primitives/link-preview.ts

@@ -0,0 +1,87 @@
+// src/primitives/link-preview.ts
+// The optional, app-supplied bare-URL → metadata hook for <kai-link-preview>, plus the
+// `link` card's data type. The card stays PURE: it renders from supplied metadata
+// and never touches the network. CORS forbids reading cross-origin HTML in the
+// browser, so there is intentionally NO built-in network implementation here — an
+// app opts in with `configureLinkPreview({ fetchMetadata })` pointing at its OWN
+// backend/proxy. See docs/superpowers/specs/2026-06-13-kc-link-embed-cards-design.md.
+import type { CardEnvelope } from './card-contract';
+
+/** Rich link / Open-Graph preview payload. The card renders from this; it never fetches. */
+export interface LinkPreviewData {
+  /** Canonical destination; opened via the contract `open` verb. */
+  url: string;
+  /** og:title — falls back to the domain. */
+  title?: string;
+  /** og:description — clamped to 3 lines. */
+  description?: string;
+  /** og:image — degrades gracefully when missing/broken. */
+  image?: string;
+  /** Alt for the preview image (defaults to title / decorative). */
+  imageAlt?: string;
+  /** Site favicon. */
+  favicon?: string;
+  /** Display domain; derived from `url` when omitted. */
+  domain?: string;
+  /** og:site_name; preferred over `domain` when present. */
+  siteName?: string;
+}
+
+/** The full envelope an agent/server emits for a link preview card. */
+export type LinkPreviewEnvelope = CardEnvelope<'link', LinkPreviewData>;
+
+/** The `type` discriminator for link preview cards. */
+export const LINK_PREVIEW_TYPE = 'link' as const;
+
+/** App-supplied resolver: a bare URL → (partial) OG metadata. Usually hits YOUR backend. */
+export type LinkMetadataFetcher = (url: string) => Promise<Partial<LinkPreviewData>>;
+
+let fetcher: LinkMetadataFetcher | undefined;
+
+/**
+ * App opt-in: supply a function (usually hitting YOUR backend/proxy) that resolves
+ * a bare URL to OG metadata. CORS forbids reading cross-origin HTML in the browser,
+ * so there is intentionally NO default network implementation.
+ */
+export function configureLinkPreview(opts: { fetchMetadata: LinkMetadataFetcher }): void {
+  fetcher = opts.fetchMetadata;
+}
+
+/** True when an app has registered a fetcher (the bare-URL path is available). */
+export function hasLinkPreviewFetcher(): boolean {
+  return fetcher !== undefined;
+}
+
+/**
+ * Used by LinkPreview ONLY when the envelope lacks metadata AND a fetcher is set.
+ * Returns the merged metadata or throws (card shows its fallback/error state).
+ */
+export async function resolveLinkMetadata(url: string): Promise<Partial<LinkPreviewData>> {
+  if (!fetcher) throw new Error('No link-preview fetcher configured');
+  return fetcher(url);
+}
+
+/** Test-only: clear the configured fetcher so tests stay isolated. */
+export function __resetLinkPreviewForTests(): void {
+  fetcher = undefined;
+}
+
+/** Derive a clean display domain from a URL (strips a leading `www.`). `undefined` if unparseable. */
+export function deriveDomain(url: string): string | undefined {
+  try {
+    return new URL(url).hostname.replace(/^www\./, '');
+  } catch {
+    return undefined;
+  }
+}
+
+const RENDERABLE_SCHEMES = ['http:', 'https:'];
+
+/** True when `url` is a syntactically valid http(s) URL (the only renderable link schemes). */
+export function isRenderableLink(url: string): boolean {
+  try {
+    return RENDERABLE_SCHEMES.includes(new URL(url).protocol);
+  } catch {
+    return false;
+  }
+}

package/src/primitives/pdf-preview.ts

@@ -0,0 +1,121 @@
+// src/primitives/pdf-preview.ts
+// On-demand PDF renderer built on pdf.js, loaded from a CDN only when a PDF is
+// actually shown — so a component set that never renders a PDF ships and runs with
+// ZERO pdf.js bytes (the ~482 KB gzip library is never fetched). When a PDF does
+// appear, pdf.js is dynamically imported from the pinned CDN build and every page
+// is rendered to a <canvas>. Hosts override the loader (self-host / CSP / pin) or
+// disable inline rendering via configurePdfPreview(). Mirrors highlighter.ts.
+
+/** Minimal shape of the pdf.js module + objects we rely on. */
+export interface PdfViewportLike {
+  width: number;
+  height: number;
+}
+export interface PdfPageLike {
+  getViewport(opts: { scale: number }): PdfViewportLike;
+  render(opts: {
+    canvasContext: CanvasRenderingContext2D | null;
+    viewport: PdfViewportLike;
+  }): { promise: Promise<void> };
+}
+export interface PdfDocumentLike {
+  numPages: number;
+  getPage(n: number): Promise<PdfPageLike>;
+}
+export interface PdfjsLike {
+  getDocument(src: { url: string }): { promise: Promise<PdfDocumentLike> };
+  GlobalWorkerOptions: { workerSrc: string };
+}
+
+export interface PdfPreviewOptions {
+  /** Turn inline PDF rendering on/off globally. When false, always show the card. */
+  enabled?: boolean;
+  /** Override the pdf.js module loader (self-host / CSP / version pin). */
+  load?: () => Promise<PdfjsLike>;
+  /** Worker URL. Default = the matching jsDelivr worker for the pinned version. */
+  workerSrc?: string;
+}
+
+/** Pinned, exact (reproducible) — NOT a range. */
+const PDFJS_VERSION = '6.0.227';
+const CDN = `https://cdn.jsdelivr.net/npm/pdfjs-dist@${PDFJS_VERSION}/build`;
+const DEFAULT_LOAD = (): Promise<PdfjsLike> =>
+  // Template literal + @vite-ignore keeps this a runtime fetch (never bundled).
+  import(/* @vite-ignore */ `${CDN}/pdf.min.mjs`) as Promise<PdfjsLike>;
+const DEFAULT_WORKER_SRC = `${CDN}/pdf.worker.min.mjs`;
+
+let enabled = true;
+let loader: () => Promise<PdfjsLike> = DEFAULT_LOAD;
+let workerSrc = DEFAULT_WORKER_SRC;
+
+export function configurePdfPreview(options: PdfPreviewOptions): void {
+  if (options.enabled !== undefined) enabled = options.enabled;
+  if (options.workerSrc !== undefined) workerSrc = options.workerSrc;
+  if (options.load !== undefined) {
+    loader = options.load;
+    pdfjsPromise = null;
+  }
+}
+
+export function isPdfPreviewEnabled(): boolean {
+  return enabled;
+}
+
+export function __resetPdfPreviewForTests(): void {
+  enabled = true;
+  loader = DEFAULT_LOAD;
+  workerSrc = DEFAULT_WORKER_SRC;
+  pdfjsPromise = null;
+}
+
+let pdfjsPromise: Promise<PdfjsLike> | null = null;
+
+/** Load pdf.js once (singleton); set the worker src. Re-loads if the loader changed. */
+function loadPdfjs(): Promise<PdfjsLike> {
+  if (!pdfjsPromise) {
+    const active = loader;
+    pdfjsPromise = (async () => {
+      const mod = await active();
+      const pdfjs = ((mod as unknown as { default?: PdfjsLike }).default ?? mod) as PdfjsLike;
+      pdfjs.GlobalWorkerOptions.workerSrc = workerSrc;
+      return pdfjs;
+    })();
+  }
+  return pdfjsPromise;
+}
+
+/**
+ * Render EVERY page of the PDF at `url` into `container` as stacked <canvas>
+ * elements fit to `pxWidth` CSS pixels (rendered at devicePixelRatio for
+ * crispness). Clears `container` first. Resolves `{ pages }`. THROWS on
+ * load / CORS / parse failure — the caller catches and shows the fallback card.
+ */
+export async function renderPdfInto(
+  url: string,
+  container: HTMLElement,
+  pxWidth: number,
+): Promise<{ pages: number }> {
+  const pdfjs = await loadPdfjs();
+  const doc = await pdfjs.getDocument({ url }).promise;
+  container.replaceChildren();
+  const dpr =
+    typeof window !== 'undefined' && window.devicePixelRatio ? window.devicePixelRatio : 1;
+  for (let n = 1; n <= doc.numPages; n++) {
+    const page = await doc.getPage(n);
+    const base = page.getViewport({ scale: 1 });
+    const scale = base.width > 0 ? pxWidth / base.width : 1;
+    const viewport = page.getViewport({ scale: scale * dpr });
+    const canvas = document.createElement('canvas');
+    canvas.width = Math.max(1, Math.floor(viewport.width));
+    canvas.height = Math.max(1, Math.floor(viewport.height));
+    canvas.setAttribute('role', 'img');
+    canvas.setAttribute('aria-label', `Page ${n}`);
+    canvas.style.width = '100%';
+    canvas.style.height = 'auto';
+    canvas.style.display = 'block';
+    const ctx = canvas.getContext('2d');
+    container.appendChild(canvas);
+    await page.render({ canvasContext: ctx, viewport }).promise;
+  }
+  return { pages: doc.numPages };
+}

package/src/primitives/use-auto-resize.ts

@@ -0,0 +1,31 @@
+import { onCleanup } from 'solid-js';
+
+interface UseAutoResizeOptions {
+  maxHeight?: number;
+}
+
+export function useAutoResize(options: UseAutoResizeOptions = {}) {
+  let textareaEl: HTMLTextAreaElement | undefined;
+
+  function resize() {
+    if (!textareaEl) return;
+    textareaEl.style.height = 'auto';
+    const scrollHeight = textareaEl.scrollHeight;
+    if (options.maxHeight && scrollHeight > options.maxHeight) {
+      textareaEl.style.height = `${options.maxHeight}px`;
+      textareaEl.style.overflowY = 'auto';
+    } else {
+      textareaEl.style.height = `${scrollHeight}px`;
+      textareaEl.style.overflowY = 'hidden';
+    }
+  }
+
+  function ref(el: HTMLTextAreaElement) {
+    textareaEl = el;
+    el.addEventListener('input', resize);
+    requestAnimationFrame(resize);
+    onCleanup(() => el.removeEventListener('input', resize));
+  }
+
+  return { ref, resize };
+}

package/src/primitives/use-resize-observer.ts

@@ -0,0 +1,12 @@
+/** Observe an element's content height; invoke `onHeight` when it changes by more than
+ *  THRESHOLD px (hysteresis kills sub-pixel oscillation — H-J). Returns a disposer. */
+const THRESHOLD = 1;
+export function observeContentHeight(el: Element, onHeight: (height: number) => void): () => void {
+  let last = -1;
+  const ro = new ResizeObserver((entries) => {
+    const h = entries[entries.length - 1]?.contentRect.height ?? el.getBoundingClientRect().height;
+    if (last < 0 || Math.abs(h - last) > THRESHOLD) { last = h; onHeight(h); }
+  });
+  ro.observe(el);
+  return () => ro.disconnect();
+}