@hachej/boring-ui-kit 0.4.11 → 0.4.13

package/r/documents.json

@@ -4,20 +4,22 @@
   "title": "Documents: the Library, a file and its revisions",
   "description": "The workspace's Library as the list, the chosen file in its viewer and its retained revisions beside it (an older one opens read-only). DocumentSheet opens one document over the app for a host's « Voir la fiche », with an optional « Toutes les fiches ». Every read goes through one revisionProvider binding.",
   "dependencies": [
-    "@hachej/boring-ui-kit@^0.4.11",
-    "@hachej/boring-files@^0.4.11",
+    "@hachej/boring-ui-kit@^0.4.13",
+    "@hachej/boring-files@^0.4.13",
     "react@^19.0.0",
     "lucide-react@^1.51.0"
   ],
   "registryDependencies": [
-    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.11/r/theme.json",
-    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.11/r/utils.json",
-    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.11/r/button.json",
-    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.11/r/pi-chat.json",
-    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.11/r/pi-app.json",
-    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.11/r/app-shell.json",
-    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.11/r/file-tree.json",
-    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.11/r/viewers.json",
+    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.13/r/theme.json",
+    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.13/r/utils.json",
+    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.13/r/button.json",
+    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.13/r/pi-artifacts.json",
+    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.13/r/pi-app.json",
+    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.13/r/app-shell.json",
+    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.13/r/file-tree.json",
+    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.13/r/viewer-frame.json",
+    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.13/r/viewer-image.json",
+    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.13/r/viewer-pdf.json",
     "drawer",
     "button",
     "scroll-area",
@@ -26,7 +28,7 @@
   "files": [
     {
       "path": "registry/documents/documents.tsx",
-      "content": "'use client';\n\n// The documents screen: the workspace's Library is the list (`ListDetail`: beside the file on a wide screen, one pane at a time on a phone);\n// the chosen file opens in the same viewer the Library uses (editable where it edits); its Revisions sit beside it. Every revision row opens\n// that exact revision read-only, and « Back to editing » returns to the file. The editor stays mounted while a revision is inspected, so its\n// unsaved edits survive; leaving the file with unsaved edits asks first. Every read goes through the one `revisionProvider` the host binds.\nimport { useCallback, useEffect, useMemo, useRef, useState } from 'react';\nimport { Button } from '@/components/ui/button';\nimport { Separator } from '@/components/ui/separator';\nimport { createFileTreeController } from '@hachej/boring-ui-kit/file-tree';\nimport type { FileTreeController } from '@hachej/boring-ui-kit/file-tree';\nimport { FileTreeView } from '../file-tree/file-tree';\nimport type { RevisionProvider } from '@hachej/boring-files/revision';\nimport { mediaTypeOf, viewerKindOf } from '@hachej/boring-files/file-types';\nimport { checkBlobBase, withBlobPointers } from '@hachej/boring-files/blob';\nimport type { ViewerKind } from '@hachej/boring-files/file-types';\nimport { ListDetail } from '../app-shell/list-detail';\nimport { ArtifactPanel } from '../pi-app/artifact-panel';\nimport type { ArtifactDescriptor } from '../pi-chat/artifact';\nimport type { CustomViewers, ViewerOptions } from '../pi-app/artifact-panel';\nimport { FileViewer } from '../pi-app/file-viewer';\nimport { ImagePane } from '../viewers/image-pane';\nimport { PdfPane } from '../viewers/pdf-pane';\nimport { ViewerFrame } from '../viewers/viewer-frame';\nimport { useViewerText } from '../viewers/viewer-window';\nimport { cn } from '../utils/utils';\nimport { Revisions } from './revisions';\nimport type { DocumentsLabels } from './documents-labels';\nimport { documentsLabels, DocumentsWords } from './words';\nimport type { DocumentsLocale } from './words';\n\nexport interface DocumentsProps {\n  /** The workspace's revision provider (the files guide's `connectRevisionProvider`, or a host's own binding). Borrowed: the host disposes it. */\n  readonly provider: RevisionProvider;\n  readonly locale?: DocumentsLocale | undefined;\n  /** The block's own words, over `documentsLabels` (the viewers' words follow `locale`). */\n  readonly labels?: Partial<DocumentsLabels> | undefined;\n  /** Host viewers by kind, as for the Library (for example a canvas). */\n  readonly viewers?: CustomViewers | undefined;\n  readonly share?: ViewerOptions['share'];\n  /** Where the host serves the bytes of large files (blob pointers): a same-origin path starting with `/`, default `/_files/`. */\n  readonly blobBase?: string | undefined;\n}\n\nconst nameOf = (path: string) => path.split('/').pop() || path;\n\n/** The workspace's change feed as a counter: it moves on every change, so the listings and the revisions are read again. */\nfunction useWorkspaceVersion(provider: RevisionProvider): number {\n  const [version, setVersion] = useState(0);\n  useEffect(() => {\n    if (!provider.changes) return undefined;\n    const abort = new AbortController();\n    void (async () => {\n      try { for await (const change of provider.changes!({ signal: abort.signal })) { void change; setVersion(current => current + 1); } } catch { /* the binding ended the feed: the listings stay as they are */ }\n    })();\n    return () => abort.abort();\n  }, [provider]);\n  return version;\n}\n\n/** The Library's tree over the provider: created and disposed with the binding, read again when the workspace changes. */\nfunction useFileTree(provider: RevisionProvider, version: number, blobBase: string): FileTreeController | undefined {\n  const [tree, setTree] = useState<FileTreeController>();\n  useEffect(() => {\n    const next = createFileTreeController({ revisionProvider: withBlobPointers(provider, blobBase) });\n    setTree(next);\n    void next.refresh();\n    return () => next.dispose();\n  }, [provider, blobBase]);\n  useEffect(() => {\n    if (!tree || version === 0) return;\n    const { query, expanded } = tree.getSnapshot();\n    if (query) void tree.search(query);\n    else for (const directory of ['', ...expanded]) void tree.refresh(directory);\n  }, [tree, version]);\n  return tree;\n}\n\n/**\n * The provider as it reads one revision: every read of the returned client is the exact `revision`, over the same provider (a reload in a\n * pinned view re-reads that revision, never the latest). It is for read-only views only.\n */\nfunction pinnedProviderOf(provider: RevisionProvider, revision: string): RevisionProvider {\n  return { ...provider, read: (request, signal) => provider.read({ target: request.target, revision: { kind: 'exact', value: revision } }, signal) };\n}\n\n/** An image or PDF revision, read exactly and shown in the viewer's read-only pane. */\nfunction BinaryRevision({ provider, path, revision, kind, labels, onClose }: {\n  readonly provider: RevisionProvider;\n  readonly path: string;\n  readonly revision: string;\n  readonly kind: 'image' | 'pdf';\n  readonly labels: DocumentsLabels;\n  readonly onClose: () => void;\n}) {\n  const [state, setState] = useState<{ readonly kind: 'loading' } | { readonly kind: 'failed' } | { readonly kind: 'ready'; readonly bytes: Uint8Array; readonly mediaType: string }>({ kind: 'loading' });\n  const { labels: viewer } = useViewerText();\n  useEffect(() => {\n    const abort = new AbortController();\n    setState({ kind: 'loading' });\n    provider.read({ target: provider.locate(path), revision: { kind: 'exact', value: revision } }, abort.signal).then(result => {\n      if (!abort.signal.aborted) setState(result.kind === 'available' ? { kind: 'ready', bytes: result.snapshot.bytes, mediaType: result.snapshot.mediaType } : { kind: 'failed' });\n    }, () => { if (!abort.signal.aborted) setState({ kind: 'failed' }); });\n    return () => abort.abort();\n  }, [provider, path, revision]);\n  const status = { label: viewer.readOnly, kind: 'read-only' as const };\n  if (state.kind !== 'ready') return <ViewerFrame title={nameOf(path)} status={status} onClose={onClose}>\n    <p role=\"status\" className=\"m-0 p-4 text-sm text-muted-foreground\">{state.kind === 'loading' ? labels.revisionsLoading : labels.revisionLoadFailed}</p>\n  </ViewerFrame>;\n  return kind === 'image'\n    ? <ImagePane name={nameOf(path)} mediaType={state.mediaType} bytes={state.bytes} status={status} onClose={onClose} />\n    : <PdfPane name={nameOf(path)} bytes={state.bytes} status={status} onClose={onClose} />;\n}\n\n/** One revision of the file, read-only, with « Back to editing ». Text, Markdown and HTML use the artifact panel's pinned view. */\nfunction OlderVersion({ provider, path, revision, options, labels, onBack, onClose }: {\n  readonly provider: RevisionProvider;\n  readonly path: string;\n  readonly revision: string;\n  readonly options: ViewerOptions;\n  readonly labels: DocumentsLabels;\n  readonly onBack: () => void;\n  readonly onClose: () => void;\n}) {\n  const kind: ViewerKind = viewerKindOf(path);\n  const pinned = useMemo(() => pinnedProviderOf(provider, revision), [provider, revision]);\n  const type = kind === 'markdown' ? 'markdown' : kind === 'html' ? 'html' : kind === 'text' ? 'code' : undefined;\n  const artifact: ArtifactDescriptor | undefined = type === undefined ? undefined\n    : { schema: 'boring.artifact', version: 1, title: nameOf(path), type, mediaType: mediaTypeOf(path), target: provider.locate(path), revision };\n  const bar = <>\n    <div className=\"flex shrink-0 items-center gap-2 px-3 py-2\">\n      <span role=\"status\" className=\"min-w-0 flex-1 truncate text-sm font-medium\">{labels.readOnlyRevision}</span>\n      <Button variant=\"ghost\" data-testid=\"back-to-editing\" onClick={onBack}>{labels.backToEditing}</Button>\n    </div>\n    <Separator />\n  </>;\n  let body;\n  if (artifact) body = <ArtifactPanel active={{ descriptor: artifact, follow: false }} versions={[]} options={{ ...options, client: pinned }} onSelect={onBack} onClose={onClose} />;\n  else if (kind === 'image' || kind === 'pdf') body = <BinaryRevision provider={provider} path={path} revision={revision} kind={kind} labels={labels} onClose={onClose} />;\n  else body = <ViewerFrame title={nameOf(path)} onClose={onClose}><p role=\"status\" className=\"m-0 p-4 text-sm text-muted-foreground\">{labels.unsupportedPreview}</p></ViewerFrame>;\n  return <div data-testid=\"revision-view\" data-kind={kind} data-revision={revision} className=\"flex h-full min-h-0 flex-1 flex-col\">\n    {bar}\n    <div className=\"flex min-h-0 flex-1 flex-col\">{body}</div>\n  </div>;\n}\n\nfunction DocumentDetail({ provider, path, version, options, labels, locale, older, onDirty, onOpenRevision, onBack, onClose }: {\n  readonly provider: RevisionProvider;\n  readonly path: string;\n  readonly version: number;\n  readonly options: ViewerOptions;\n  readonly labels: DocumentsLabels;\n  readonly locale: DocumentsLocale;\n  /** The older revision on show, `undefined` for the editable file. */\n  readonly older: string | undefined;\n  readonly onDirty: (unsaved: boolean) => void;\n  readonly onOpenRevision: (revision: string) => void;\n  readonly onBack: () => void;\n  readonly onClose: () => void;\n}) {\n  return <div data-testid=\"documents-detail\" className=\"flex h-full min-h-0 flex-col md:flex-row\">\n    <div className=\"flex min-h-0 min-w-0 flex-1 flex-col\">\n      {/* The editor stays mounted (hidden) while a revision is on show, so its unsaved edits are kept. */}\n      <div className={cn('min-h-0 flex-1 flex-col', older === undefined ? 'flex' : 'hidden')}>\n        <FileViewer path={path} locator={provider.locate(path)} options={options} onClose={onClose} onUnsavedChange={onDirty} />\n      </div>\n      {older !== undefined && <OlderVersion provider={provider} path={path} revision={older} options={options} labels={labels} onBack={onBack} onClose={onClose} />}\n    </div>\n    <Separator className=\"md:hidden\" />\n    <Separator orientation=\"vertical\" className=\"max-md:hidden\" />\n    <aside className=\"flex max-h-[40%] min-h-0 shrink-0 flex-col overflow-hidden md:max-h-none md:w-72\">\n      <Revisions provider={provider} path={path} version={version} selected={older} locale={locale} labels={labels} onOpen={onOpenRevision} />\n    </aside>\n  </div>;\n}\n\nexport function Documents({ provider, locale, labels: given, viewers, share, blobBase: givenBase }: DocumentsProps) {\n  const labels = documentsLabels(locale, given);\n  const language: DocumentsLocale = locale === 'fr' ? 'fr' : 'en';\n  const version = useWorkspaceVersion(provider);\n  const blobBase = checkBlobBase(givenBase);\n  const tree = useFileTree(provider, version, blobBase);\n  const [path, setPath] = useState<string>();\n  // An older revision of the file on show (`undefined`: the editable file).\n  const [pinned, setPinned] = useState<{ readonly path: string; readonly revision: string }>();\n  // The file's unsaved edits, as its viewer reports them. A change of file or a close that would drop them asks first.\n  const dirty = useRef(false);\n  const onDirty = useCallback((unsaved: boolean) => { dirty.current = unsaved; }, []);\n  const mayLeave = () => !dirty.current || window.confirm(labels.discardChanges);\n  const options = useMemo<ViewerOptions>(() => ({ client: provider, identity: provider.identity, blobBase, ...(viewers ? { viewers } : {}), ...(share ? { share } : {}) }), [provider, viewers, share, blobBase]);\n  const choose = (next: string) => {\n    if (next === path || !mayLeave()) return;\n    setPath(next);\n    setPinned(undefined);\n  };\n  const closeFile = () => { if (!mayLeave()) return; setPath(undefined); setPinned(undefined); };\n  const list = tree ? <div className=\"min-h-0\">\n    <FileTreeView controller={tree} onOpen={choose} selectedPath={path} locale={language} upload={false} history={false} />\n  </div> : null;\n  const older = path !== undefined && pinned?.path === path ? pinned.revision : undefined;\n  // `null` (nothing chosen) is what lets a phone show the list alone: ListDetail stacks the detail only when there is one.\n  const detail = path === undefined ? null\n    : <DocumentDetail key={path} provider={provider} path={path} version={version} options={options} labels={labels} locale={language} older={older}\n      onDirty={onDirty} onOpenRevision={revision => setPinned({ path, revision })} onBack={() => setPinned(undefined)} onClose={closeFile} />;\n  return <DocumentsWords locale={locale}>\n    <ListDetail list={list} detail={detail} onBack={closeFile} />\n  </DocumentsWords>;\n}\n",
+      "content": "'use client';\n\n// The documents screen: the workspace's Library is the list (`ListDetail`: beside the file on a wide screen, one pane at a time on a phone);\n// the chosen file opens in the same viewer the Library uses (editable where it edits); its Revisions sit beside it. Every revision row opens\n// that exact revision read-only, and « Back to editing » returns to the file. The editor stays mounted while a revision is inspected, so its\n// unsaved edits survive; leaving the file with unsaved edits asks first. Every read goes through the one `revisionProvider` the host binds.\nimport { Suspense, useCallback, useEffect, useMemo, useRef, useState } from 'react';\nimport { Button } from '@/components/ui/button';\nimport { Separator } from '@/components/ui/separator';\nimport { createFileTreeController } from '@hachej/boring-ui-kit/file-tree';\nimport type { FileTreeController } from '@hachej/boring-ui-kit/file-tree';\nimport { FileTreeView } from '../file-tree/file-tree';\nimport type { RevisionProvider } from '@hachej/boring-files/revision';\nimport { mediaTypeOf, viewerKindOf } from '@hachej/boring-files/file-types';\nimport { checkBlobBase, withBlobPointers } from '@hachej/boring-files/blob';\nimport type { ViewerKind } from '@hachej/boring-files/file-types';\nimport { ListDetail } from '../app-shell/list-detail';\nimport { ArtifactPanel } from '../pi-app/artifact-panel';\nimport type { ArtifactDescriptor } from '../pi-artifacts/artifact';\nimport type { CustomViewers, ViewerOptions } from '../pi-app/artifact-panel';\nimport { FileViewer } from '../pi-app/file-viewer';\nimport { lazyView, ViewLoading } from '../pi-app/viewer-kinds';\nimport { imageKind } from '../viewer-image/image-kind';\nimport { pdfKind } from '../viewer-pdf/pdf-kind';\nimport { ViewerFrame } from '../viewer-frame/viewer-frame';\nimport { useViewerText } from '../viewer-frame/viewer-window';\nimport { cn } from '../utils/utils';\nimport { Revisions } from './revisions';\nimport type { DocumentsLabels } from './documents-labels';\nimport { documentsLabels, DocumentsWords } from './words';\nimport type { DocumentsLocale } from './words';\n\nexport interface DocumentsProps {\n  /** The workspace's revision provider (the files guide's `connectRevisionProvider`, or a host's own binding). Borrowed: the host disposes it. */\n  readonly provider: RevisionProvider;\n  readonly locale?: DocumentsLocale | undefined;\n  /** The block's own words, over `documentsLabels` (the viewers' words follow `locale`). */\n  readonly labels?: Partial<DocumentsLabels> | undefined;\n  /** Host viewers by kind, as for the Library (for example a canvas). */\n  readonly viewers?: CustomViewers | undefined;\n  readonly share?: ViewerOptions['share'];\n  /** Where the host serves the bytes of large files (blob pointers): a same-origin path starting with `/`, default `/_files/`. */\n  readonly blobBase?: string | undefined;\n}\n\nconst nameOf = (path: string) => path.split('/').pop() || path;\n\n/** The workspace's change feed as a counter: it moves on every change, so the listings and the revisions are read again. */\nfunction useWorkspaceVersion(provider: RevisionProvider): number {\n  const [version, setVersion] = useState(0);\n  useEffect(() => {\n    if (!provider.changes) return undefined;\n    const abort = new AbortController();\n    void (async () => {\n      try { for await (const change of provider.changes!({ signal: abort.signal })) { void change; setVersion(current => current + 1); } } catch { /* the binding ended the feed: the listings stay as they are */ }\n    })();\n    return () => abort.abort();\n  }, [provider]);\n  return version;\n}\n\n/** The Library's tree over the provider: created and disposed with the binding, read again when the workspace changes. */\nfunction useFileTree(provider: RevisionProvider, version: number, blobBase: string): FileTreeController | undefined {\n  const [tree, setTree] = useState<FileTreeController>();\n  useEffect(() => {\n    const next = createFileTreeController({ revisionProvider: withBlobPointers(provider, blobBase) });\n    setTree(next);\n    void next.refresh();\n    return () => next.dispose();\n  }, [provider, blobBase]);\n  useEffect(() => {\n    if (!tree || version === 0) return;\n    const { query, expanded } = tree.getSnapshot();\n    if (query) void tree.search(query);\n    else for (const directory of ['', ...expanded]) void tree.refresh(directory);\n  }, [tree, version]);\n  return tree;\n}\n\n/**\n * The provider as it reads one revision: every read of the returned client is the exact `revision`, over the same provider (a reload in a\n * pinned view re-reads that revision, never the latest). It is for read-only views only.\n */\nfunction pinnedProviderOf(provider: RevisionProvider, revision: string): RevisionProvider {\n  return { ...provider, read: (request, signal) => provider.read({ target: request.target, revision: { kind: 'exact', value: revision } }, signal) };\n}\n\n/** An image or PDF revision, read exactly and shown in the viewer's read-only pane. */\nfunction BinaryRevision({ provider, path, revision, kind, labels, onClose }: {\n  readonly provider: RevisionProvider;\n  readonly path: string;\n  readonly revision: string;\n  readonly kind: 'image' | 'pdf';\n  readonly labels: DocumentsLabels;\n  readonly onClose: () => void;\n}) {\n  const [state, setState] = useState<{ readonly kind: 'loading' } | { readonly kind: 'failed' } | { readonly kind: 'ready'; readonly bytes: Uint8Array; readonly mediaType: string }>({ kind: 'loading' });\n  const { labels: viewer } = useViewerText();\n  useEffect(() => {\n    const abort = new AbortController();\n    setState({ kind: 'loading' });\n    provider.read({ target: provider.locate(path), revision: { kind: 'exact', value: revision } }, abort.signal).then(result => {\n      if (!abort.signal.aborted) setState(result.kind === 'available' ? { kind: 'ready', bytes: result.snapshot.bytes, mediaType: result.snapshot.mediaType } : { kind: 'failed' });\n    }, () => { if (!abort.signal.aborted) setState({ kind: 'failed' }); });\n    return () => abort.abort();\n  }, [provider, path, revision]);\n  const status = { label: viewer.readOnly, kind: 'read-only' as const };\n  if (state.kind !== 'ready') return <ViewerFrame title={nameOf(path)} status={status} onClose={onClose}>\n    <p role=\"status\" className=\"m-0 p-4 text-sm text-muted-foreground\">{state.kind === 'loading' ? labels.revisionsLoading : labels.revisionLoadFailed}</p>\n  </ViewerFrame>;\n  // The panes load the first time an image or a PDF revision opens (D-257), like the file viewer's.\n  const ImagePane = lazyView(imageKind.load), PdfPane = lazyView(pdfKind.load);\n  return <Suspense fallback={<ViewerFrame testId=\"viewer-pending\" title={nameOf(path)} status={status} onClose={onClose}><ViewLoading label={viewer.loading} /></ViewerFrame>}>\n    {kind === 'image'\n      ? <ImagePane name={nameOf(path)} mediaType={state.mediaType} bytes={state.bytes} status={status} onClose={onClose} />\n      : <PdfPane name={nameOf(path)} bytes={state.bytes} status={status} onClose={onClose} />}\n  </Suspense>;\n}\n\n/** One revision of the file, read-only, with « Back to editing ». Text, Markdown and HTML use the artifact panel's pinned view. */\nfunction OlderVersion({ provider, path, revision, options, labels, onBack, onClose }: {\n  readonly provider: RevisionProvider;\n  readonly path: string;\n  readonly revision: string;\n  readonly options: ViewerOptions;\n  readonly labels: DocumentsLabels;\n  readonly onBack: () => void;\n  readonly onClose: () => void;\n}) {\n  const kind: ViewerKind = viewerKindOf(path);\n  const pinned = useMemo(() => pinnedProviderOf(provider, revision), [provider, revision]);\n  const type = kind === 'markdown' ? 'markdown' : kind === 'html' ? 'html' : kind === 'text' ? 'code' : undefined;\n  const artifact: ArtifactDescriptor | undefined = type === undefined ? undefined\n    : { schema: 'boring.artifact', version: 1, title: nameOf(path), type, mediaType: mediaTypeOf(path), target: provider.locate(path), revision };\n  const bar = <>\n    <div className=\"flex shrink-0 items-center gap-2 px-3 py-2\">\n      <span role=\"status\" className=\"min-w-0 flex-1 truncate text-sm font-medium\">{labels.readOnlyRevision}</span>\n      <Button variant=\"ghost\" data-testid=\"back-to-editing\" onClick={onBack}>{labels.backToEditing}</Button>\n    </div>\n    <Separator />\n  </>;\n  let body;\n  if (artifact) body = <ArtifactPanel active={{ descriptor: artifact, follow: false }} versions={[]} options={{ ...options, client: pinned }} onSelect={onBack} onClose={onClose} />;\n  else if (kind === 'image' || kind === 'pdf') body = <BinaryRevision provider={provider} path={path} revision={revision} kind={kind} labels={labels} onClose={onClose} />;\n  else body = <ViewerFrame title={nameOf(path)} onClose={onClose}><p role=\"status\" className=\"m-0 p-4 text-sm text-muted-foreground\">{labels.unsupportedPreview}</p></ViewerFrame>;\n  return <div data-testid=\"revision-view\" data-kind={kind} data-revision={revision} className=\"flex h-full min-h-0 flex-1 flex-col\">\n    {bar}\n    <div className=\"flex min-h-0 flex-1 flex-col\">{body}</div>\n  </div>;\n}\n\nfunction DocumentDetail({ provider, path, version, options, labels, locale, older, onDirty, onOpenRevision, onBack, onClose }: {\n  readonly provider: RevisionProvider;\n  readonly path: string;\n  readonly version: number;\n  readonly options: ViewerOptions;\n  readonly labels: DocumentsLabels;\n  readonly locale: DocumentsLocale;\n  /** The older revision on show, `undefined` for the editable file. */\n  readonly older: string | undefined;\n  readonly onDirty: (unsaved: boolean) => void;\n  readonly onOpenRevision: (revision: string) => void;\n  readonly onBack: () => void;\n  readonly onClose: () => void;\n}) {\n  return <div data-testid=\"documents-detail\" className=\"flex h-full min-h-0 flex-col md:flex-row\">\n    <div className=\"flex min-h-0 min-w-0 flex-1 flex-col\">\n      {/* The editor stays mounted (hidden) while a revision is on show, so its unsaved edits are kept. */}\n      <div className={cn('min-h-0 flex-1 flex-col', older === undefined ? 'flex' : 'hidden')}>\n        <FileViewer path={path} locator={provider.locate(path)} options={options} onClose={onClose} onUnsavedChange={onDirty} />\n      </div>\n      {older !== undefined && <OlderVersion provider={provider} path={path} revision={older} options={options} labels={labels} onBack={onBack} onClose={onClose} />}\n    </div>\n    <Separator className=\"md:hidden\" />\n    <Separator orientation=\"vertical\" className=\"max-md:hidden\" />\n    <aside className=\"flex max-h-[40%] min-h-0 shrink-0 flex-col overflow-hidden md:max-h-none md:w-72\">\n      <Revisions provider={provider} path={path} version={version} selected={older} locale={locale} labels={labels} onOpen={onOpenRevision} />\n    </aside>\n  </div>;\n}\n\nexport function Documents({ provider, locale, labels: given, viewers, share, blobBase: givenBase }: DocumentsProps) {\n  const labels = documentsLabels(locale, given);\n  const language: DocumentsLocale = locale === 'fr' ? 'fr' : 'en';\n  const version = useWorkspaceVersion(provider);\n  const blobBase = checkBlobBase(givenBase);\n  const tree = useFileTree(provider, version, blobBase);\n  const [path, setPath] = useState<string>();\n  // An older revision of the file on show (`undefined`: the editable file).\n  const [pinned, setPinned] = useState<{ readonly path: string; readonly revision: string }>();\n  // The file's unsaved edits, as its viewer reports them. A change of file or a close that would drop them asks first.\n  const dirty = useRef(false);\n  const onDirty = useCallback((unsaved: boolean) => { dirty.current = unsaved; }, []);\n  const mayLeave = () => !dirty.current || window.confirm(labels.discardChanges);\n  const options = useMemo<ViewerOptions>(() => ({ client: provider, identity: provider.identity, blobBase, ...(viewers ? { viewers } : {}), ...(share ? { share } : {}) }), [provider, viewers, share, blobBase]);\n  const choose = (next: string) => {\n    if (next === path || !mayLeave()) return;\n    setPath(next);\n    setPinned(undefined);\n  };\n  const closeFile = () => { if (!mayLeave()) return; setPath(undefined); setPinned(undefined); };\n  const list = tree ? <div className=\"min-h-0\">\n    <FileTreeView controller={tree} onOpen={choose} selectedPath={path} locale={language} upload={false} history={false} />\n  </div> : null;\n  const older = path !== undefined && pinned?.path === path ? pinned.revision : undefined;\n  // `null` (nothing chosen) is what lets a phone show the list alone: ListDetail stacks the detail only when there is one.\n  const detail = path === undefined ? null\n    : <DocumentDetail key={path} provider={provider} path={path} version={version} options={options} labels={labels} locale={language} older={older}\n      onDirty={onDirty} onOpenRevision={revision => setPinned({ path, revision })} onBack={() => setPinned(undefined)} onClose={closeFile} />;\n  return <DocumentsWords locale={locale}>\n    <ListDetail list={list} detail={detail} onBack={closeFile} />\n  </DocumentsWords>;\n}\n",
       "type": "registry:component",
       "target": "components/documents/documents.tsx"
     },
@@ -44,7 +46,7 @@
     },
     {
       "path": "registry/documents/words.tsx",
-      "content": "'use client';\n\n// The words the documents block shows: its own, and the viewers' (the pi-app labels the file viewer and the artifact panel read, and the\n// viewer window's labels the viewer bars read). One locale for all of them: `fr` takes the French sets, anything else English, and a\n// `labels` object overrides any word of the block's own.\nimport type { ReactNode } from 'react';\nimport { defaultAppIcons, defaultAppLabels, AppTextProvider } from '../pi-app/app-labels';\nimport { frenchAppLabels } from '../pi-app/app-labels-fr';\nimport { defaultViewerIcons, defaultViewerLabels, ViewerWindowProvider } from '../viewers/viewer-window';\nimport { frenchViewerLabels } from '../viewers/viewer-labels-fr';\nimport { defaultDocumentsLabels, frenchDocumentsLabels } from './documents-labels';\nimport type { DocumentsLabels } from './documents-labels';\n\nexport type DocumentsLocale = 'en' | 'fr';\n\n/** The block's own words for `locale`, with the host's overrides. */\nexport function documentsLabels(locale: DocumentsLocale | undefined, given: Partial<DocumentsLabels> | undefined): DocumentsLabels {\n  return { ...(locale === 'fr' ? frenchDocumentsLabels : defaultDocumentsLabels), ...given };\n}\n\n/** Provides the app's and the viewers' words for `locale` to everything below (the file viewer, the artifact panel, the viewer bars). */\nexport function DocumentsWords({ locale, children }: { readonly locale: DocumentsLocale | undefined; readonly children: ReactNode }) {\n  const fr = locale === 'fr';\n  return <AppTextProvider value={{ labels: fr ? frenchAppLabels : defaultAppLabels, icons: defaultAppIcons }}>\n    <ViewerWindowProvider value={{ labels: fr ? frenchViewerLabels : defaultViewerLabels, icons: defaultViewerIcons }}>{children}</ViewerWindowProvider>\n  </AppTextProvider>;\n}\n",
+      "content": "'use client';\n\n// The words the documents block shows: its own, and the viewers' (the pi-app labels the file viewer and the artifact panel read, and the\n// viewer window's labels the viewer bars read). One locale for all of them: `fr` takes the French sets, anything else English, and a\n// `labels` object overrides any word of the block's own.\nimport type { ReactNode } from 'react';\nimport { defaultAppIcons, defaultAppLabels, AppTextProvider } from '../pi-app/app-labels';\nimport { frenchAppLabels } from '../pi-app/app-labels-fr';\nimport { defaultViewerIcons, defaultViewerLabels, ViewerWindowProvider } from '../viewer-frame/viewer-window';\nimport { frenchViewerLabels } from '../viewer-frame/viewer-labels-fr';\nimport { defaultDocumentsLabels, frenchDocumentsLabels } from './documents-labels';\nimport type { DocumentsLabels } from './documents-labels';\n\nexport type DocumentsLocale = 'en' | 'fr';\n\n/** The block's own words for `locale`, with the host's overrides. */\nexport function documentsLabels(locale: DocumentsLocale | undefined, given: Partial<DocumentsLabels> | undefined): DocumentsLabels {\n  return { ...(locale === 'fr' ? frenchDocumentsLabels : defaultDocumentsLabels), ...given };\n}\n\n/** Provides the app's and the viewers' words for `locale` to everything below (the file viewer, the artifact panel, the viewer bars). */\nexport function DocumentsWords({ locale, children }: { readonly locale: DocumentsLocale | undefined; readonly children: ReactNode }) {\n  const fr = locale === 'fr';\n  return <AppTextProvider value={{ labels: fr ? frenchAppLabels : defaultAppLabels, icons: defaultAppIcons }}>\n    <ViewerWindowProvider value={{ labels: fr ? frenchViewerLabels : defaultViewerLabels, icons: defaultViewerIcons }}>{children}</ViewerWindowProvider>\n  </AppTextProvider>;\n}\n",
       "type": "registry:component",
       "target": "components/documents/words.tsx"
     },

package/r/feedback-preview.json

@@ -4,7 +4,7 @@
   "title": "Feedback preview",
   "description": "PreviewBanner: a live, reversible preview of a change in the page (Approve / Discard) over `@hachej/boring-feedback/preview`, whose subagent calls models through a host gateway. Separate from `feedback` so annotation-only apps do not install the model SDK; install `feedback` first (its styles cover the banner).",
   "dependencies": [
-    "@hachej/boring-feedback@^0.4.11",
+    "@hachej/boring-feedback@^0.4.13",
     "@earendil-works/pi-ai@~1.2.0",
     "react@^19.0.0"
   ],

package/r/feedback.json

@@ -4,16 +4,17 @@
   "title": "Feedback",
   "description": "Feedback from the chat composer: one Feedback button starts feedback mode on the application page (hover, click to pin a numbered note, hold ⌥ to use the app, optional voice), and one chip carries the notes to the next message. FeedbackBar, NoteBubble, FeedbackChip with its review, useComposerFeedback for the pi-chat composer, and PickerOverlay styles. Optional, not mounted by default: PointButton, AnnotateSheet, FeedbackList and FeedbackReport. Picking, masking, anchoring and placement stay in @hachej/boring-feedback/page and /ui, so restyling cannot weaken them.",
   "dependencies": [
-    "@hachej/boring-feedback@^0.4.11",
-    "@hachej/boring-ui-kit@^0.4.11",
-    "@hachej/boring-files@^0.4.11",
+    "@hachej/boring-feedback@^0.4.13",
+    "@hachej/boring-ui-kit@^0.4.13",
+    "@hachej/boring-files@^0.4.13",
     "react@^19.0.0",
     "react-dom@^19.0.0",
     "lucide-react@^1.51.0"
   ],
   "registryDependencies": [
-    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.11/r/pi-chat.json",
-    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.11/r/utils.json",
+    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.13/r/pi-chat.json",
+    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.13/r/pi-chat-voice.json",
+    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.13/r/utils.json",
     "button",
     "toggle",
     "badge",
@@ -25,7 +26,7 @@
   "files": [
     {
       "path": "registry/feedback/feedback-session.tsx",
-      "content": "// The feedback session's look (FEEDBACK.md, \"UX\"): the note pin beside a picked element (NoteBubble: a text field with a mic inside it),\n// the slim bar and the chip with its review (optional, for hosts with no chat). Everything they show and do is the headless\n// `createFeedbackSession` from `@hachej/boring-feedback/ui` (hover labels, pins, steps, the draft and Send come from there, through the\n// privacy policy); this file is how it looks. `useComposerFeedback` adapts a session to the chat composer's optional `feedback` prop\n// (registry/pi-chat): ONE annotate toggle and a count chip, structurally, so neither item imports the other.\nimport { useEffect, useLayoutEffect, useMemo, useRef, useState, type CSSProperties, type KeyboardEvent } from 'react';\nimport { createPortal } from 'react-dom';\nimport { MicIcon, SquareIcon, XIcon } from 'lucide-react';\nimport { Button } from '@/components/ui/button';\nimport { Toggle } from '@/components/ui/toggle';\nimport { Badge } from '@/components/ui/badge';\nimport { Card } from '@/components/ui/card';\nimport { Textarea } from '@/components/ui/textarea';\nimport { readableElement } from '@hachej/boring-feedback/format';\nimport { createVoiceCapture, type VoiceCapture } from '@hachej/boring-feedback/page';\nimport { pinMark, type FeedbackSession, type FeedbackSessionSnapshot, type SessionNote } from '@hachej/boring-feedback/ui';\nimport { useHoldToRecord } from '../pi-chat/use-hold-to-record';\nimport { useExternal } from './use-external';\nimport { plainElement, withLabels, type FeedbackLabels } from './feedback-labels';\n\nconst plural = (count: number, one: string, many: string): string => `${count} ${count === 1 ? one : many}`;\n/** Notes the chip and the bar count: every note that says something (not a pin still being typed), plus the general note. */\nexport function noteCount(state: FeedbackSessionSnapshot): number {\n  return state.notes.filter(note => note.text.trim()).length + (state.general.trim() ? 1 : 0);\n}\n\nexport interface FeedbackBarProps {\n  readonly session: FeedbackSession;\n  readonly className?: string;\n  /** Docked under the chat composer (the composer's `feedback.bar`) instead of floating at the top of the page. */\n  readonly docked?: boolean;\n}\n\n/** Pins dropped while recording that have no note yet (nothing transcribed for them, or transcription failed). */\nexport function emptyPinCount(state: FeedbackSessionSnapshot): number {\n  return state.notes.filter(note => note.recorded && !note.text.trim()).length;\n}\n\n/** `mm:ss` since `since` (ms), for the recording timer. */\nexport function elapsed(ms: number): string {\n  const seconds = Math.max(0, Math.floor(ms / 1000));\n  return `${String(Math.floor(seconds / 60)).padStart(2, '0')}:${String(seconds % 60).padStart(2, '0')}`;\n}\n\n/** The running time of a recording, from when the bar saw it start; 00:00 when not recording. */\nfunction useRecordingTime(recording: boolean): string {\n  const [since, setSince] = useState<number | undefined>(undefined);\n  const [, tick] = useState(0);\n  useEffect(() => {\n    if (!recording) { setSince(undefined); return; }\n    setSince(Date.now());\n    const timer = setInterval(() => tick(value => value + 1), 500);\n    return () => clearInterval(timer);\n  }, [recording]);\n  return elapsed(since === undefined ? 0 : Date.now() - since);\n}\n\nfunction barHint(state: FeedbackSessionSnapshot): string {\n  if (state.phase === 'processing') return state.transcribing ? 'Transcribing…' : 'Preparing your feedback…';\n  if (state.problem) return state.problem;\n  if (state.voice.kind === 'starting') return 'Allow the microphone if your browser asks…';\n  if (state.voice.kind === 'recording') return state.using ? 'Recording — using the app' : 'Recording — point and talk';\n  return state.using ? 'Using the app: your clicks are recorded as steps' : 'Click what you want to comment on';\n}\n\n/**\n * Feedback mode's bar: `● Feedback · N notes · 🎙 Record · Use app · Done · ✕`. While recording: a red dot, the\n * running time, \"Recording — point and talk\" and Stop. A refused microphone is said in the bar itself, never only in a tooltip.\n */\nexport function FeedbackBar({ session, className, docked = false }: FeedbackBarProps) {\n  const state = useExternal(session);\n  const recording = state.voice.kind === 'recording';\n  const time = useRecordingTime(recording && (state.phase === 'active' || state.phase === 'processing'));\n  if (state.phase !== 'active' && state.phase !== 'processing') return null;\n  const processing = state.phase === 'processing';\n  const pins = emptyPinCount(state);\n  const voiceProblem = state.voice.kind === 'refused' ? state.voice : undefined;\n  return <Card size=\"sm\" data-boring=\"feedback\" data-feedback-ignore=\"\" role=\"toolbar\" aria-label=\"Feedback mode\" data-testid=\"feedback-bar\" data-docked={docked ? 'true' : 'false'}\n    data-using={state.using ? 'true' : 'false'} data-recording={recording ? 'true' : 'false'} data-transcribing={state.transcribing ? 'true' : 'false'}\n    className={['boring-feedback-bar', className].filter(Boolean).join(' ')}\n    onKeyDown={event => { if (event.key === 'Escape' && state.bubble) { event.stopPropagation(); session.cancelBubble(); } }}>\n    <span className=\"boring-feedback-bar-title\">Feedback</span>\n    <span className=\"boring-feedback-bar-meta\" data-testid=\"feedback-bar-count\">{plural(noteCount(state), 'note', 'notes')}{pins ? ` · ${plural(pins, 'pin', 'pins')}` : ''}</span>\n    {state.voiceAvailable && <Toggle data-testid=\"feedback-voice\" pressed={recording}\n      disabled={processing || state.voice.kind === 'starting' || state.voice.kind === 'stopping'} title={recording ? 'Stop recording' : 'Record your voice while you point: each click drops a pin, what you say becomes its note'}\n      onPressedChange={() => { void session.toggleVoice(); }}>\n      {recording ? <><SquareIcon data-icon=\"inline-start\" aria-hidden=\"true\" />Stop</> : <><MicIcon data-icon=\"inline-start\" aria-hidden=\"true\" />{state.voice.kind === 'starting' ? 'Starting…' : state.voice.kind === 'stopping' ? 'Stopping…' : 'Record'}</>}\n    </Toggle>}\n    {recording && <Badge variant=\"destructive\" role=\"status\" data-testid=\"feedback-recording\">\n      <span className=\"boring-feedback-timer\" data-testid=\"feedback-recording-time\">{time}</span></Badge>}\n    <span className=\"boring-feedback-hint\" role=\"status\" aria-live=\"polite\" data-testid=\"feedback-bar-hint\">{barHint(state)}</span>\n    {voiceProblem && <span className=\"boring-feedback-voice-problem\" role=\"alert\" data-testid=\"feedback-voice-problem\" data-code={voiceProblem.code}>{voiceProblem.reason}</span>}\n    {!processing && <Toggle data-testid=\"feedback-use-app\" pressed={state.useToggle} onPressedChange={pressed => session.setUseToggle(pressed)}>Use app</Toggle>}\n    <Button variant=\"default\" data-testid=\"feedback-done\" disabled={processing} onClick={() => { void session.done(); }}>Done</Button>\n    <Button variant=\"ghost\" size=\"icon\" data-testid=\"feedback-discard\" aria-label=\"Discard feedback\" title=\"Discard feedback\" disabled={processing} onClick={() => session.discard()}><XIcon data-icon=\"inline-start\" aria-hidden=\"true\" /></Button>\n  </Card>;\n}\n\nconst BUBBLE_WIDTH = 280;\n/** Pixels at the bottom of the viewport taken by comment mode's banner on a phone (CommentBanner, `data-feedback-point-bar=\"bottom\"`), plus a gap; 0 without it. */\nexport function pointBarInset(document: Document): number {\n  const bar = document.querySelector('[data-feedback-point-bar=\"bottom\"]');\n  const height = document.defaultView?.innerHeight ?? 768;\n  return bar ? Math.max(0, height - bar.getBoundingClientRect().top + 8) : 0;\n}\n\n/**\n * Beside the element: below it when the bubble (`size`, its measured height once drawn) fits above point mode's bar (if any), else\n * above it, else as low as it fits. Every branch is clamped to the space above the bar, so the bubble never covers it; a bubble taller\n * than that space scrolls inside it.\n */\nfunction bubblePlace(element: Element, size = 120): CSSProperties {\n  const view = element.ownerDocument.defaultView;\n  const width = view?.innerWidth ?? 1024, height = (view?.innerHeight ?? 768) - pointBarInset(element.ownerDocument);\n  const rect = element.getBoundingClientRect();\n  const left = Math.min(Math.max(8, rect.left), Math.max(8, width - BUBBLE_WIDTH - 8));\n  const below = rect.bottom + 8;\n  const above = rect.top - size - 8;\n  const lowest = Math.max(8, height - size);\n  const top = Math.min(below + size <= height ? below : above >= 8 ? above : lowest, lowest);\n  return { position: 'fixed', top, left, width: Math.min(BUBBLE_WIDTH, width - 16), maxHeight: Math.max(0, height - top), overflowY: 'auto', boxSizing: 'border-box' };\n}\n\ntype PinVoice = 'idle' | 'starting' | 'recording' | 'transcribing';\n\n/**\n * The mic inside the pin's field, held like the chat's voice message (`useHoldToRecord`, the same gesture policy as the composer and the\n * shell): press and hold to talk (Space or Enter from the keyboard), release and the transcript is added to the note and the note is kept\n * (with `useSendEachNote`, sent at once). A slide off the button, Escape or a hidden page drops the recording. A refused microphone, nothing\n * heard or a rejected transcription is said under the field and never touches the typed text. One capture (`createVoiceCapture`) per pin.\n */\nfunction PinMic({ session, transcribe, words }: { readonly session: FeedbackSession; readonly transcribe: PinTranscribe; readonly words: FeedbackLabels }) {\n  const [phase, setPhase] = useState<PinVoice>('idle');\n  const [problem, setProblem] = useState<string | undefined>(undefined);\n  const capture = useRef<VoiceCapture | null>(null);\n  const run = useRef(0);\n  const work = useRef<AbortController | null>(null);\n  // Let go before the microphone was ready: the recording ends as soon as it starts.\n  const released = useRef(false);\n  capture.current ??= createVoiceCapture();\n  // A closed pin releases the microphone and drops a transcription still in flight.\n  useEffect(() => () => { run.current += 1; capture.current?.cancel(); work.current?.abort(); }, []);\n  const finish = async (): Promise<void> => {\n    const attempt = run.current;\n    setPhase('transcribing');\n    const recording = await capture.current!.stop().catch(() => null);\n    if (attempt !== run.current) return;\n    if (!recording) { setPhase('idle'); setProblem(words.voiceNothing); return; }\n    const abort = new AbortController();\n    work.current = abort;\n    try {\n      const spoken = (await transcribe(recording.audio, abort.signal)).trim();\n      if (attempt !== run.current) return;\n      if (!spoken) { setProblem(words.voiceNothing); return; }\n      // Appended to what is typed NOW (the person may have kept typing), never replacing it.\n      const typed = session.getSnapshot().bubble?.text ?? '';\n      session.setBubbleText(`${typed}${typed === '' || /\\s$/.test(typed) ? '' : ' '}${spoken}`);\n      session.saveBubble();\n    } catch { if (attempt === run.current) setProblem(words.voiceFailed); }\n    finally { if (work.current === abort) work.current = null; if (attempt === run.current) setPhase('idle'); }\n  };\n  const hold = useHoldToRecord({\n    // Called straight from the press, so the browser ties the permission prompt to the person's gesture.\n    start: () => {\n      const attempt = ++run.current;\n      released.current = false;\n      setProblem(undefined); setPhase('starting');\n      void capture.current!.start().then(result => {\n        if (attempt !== run.current) return;\n        if (result.kind === 'refused') { setPhase('idle'); setProblem(result.reason); return; }\n        setPhase('recording');\n        if (released.current) void finish();\n      });\n    },\n    finish: () => { if (phase === 'recording') void finish(); else released.current = true; },\n    cancel: () => { run.current += 1; capture.current?.cancel(); setPhase('idle'); },\n  }, phase === 'transcribing');\n  const recording = phase === 'recording';\n  return <>\n    <Button {...hold} variant=\"ghost\" size=\"icon\" className=\"boring-feedback-pin-mic min-h-11 min-w-11 touch-none select-none\" data-testid=\"feedback-bubble-mic\" data-state={phase}\n      aria-pressed={recording || phase === 'starting'} aria-label={recording ? words.voiceStop : words.voiceRecord} title={recording ? words.voiceStop : words.voiceRecord} disabled={phase === 'transcribing'}>\n      {phase === 'transcribing' ? <span role=\"status\" aria-label={words.voiceTranscribing}>…</span>\n        : recording ? <SquareIcon data-icon=\"inline-start\" aria-hidden=\"true\" /> : <MicIcon data-icon=\"inline-start\" aria-hidden=\"true\" />}\n    </Button>\n    {problem && <span className=\"boring-feedback-voice-problem\" role=\"alert\" data-testid=\"feedback-bubble-voice-problem\">{problem}</span>}\n  </>;\n}\n\n/** Turns a recording into text (`signal` aborts when the pin closes); a rejection keeps what was typed. */\nexport type PinTranscribe = (audio: Blob, signal: AbortSignal) => Promise<string>;\n\n/**\n * The pin beside a picked element: a text field with a mic inside it, \"Add note\" (Enter) and Cancel (Esc). Enter saves, Shift-Enter for a\n * new line, Esc discards the pin. The element is named in plain words (`plainElement`). On a phone it keeps clear of the comment banner. `transcribe` turns the mic's recording into text; without it there is no mic.\n */\nexport function NoteBubble({ session, labels, transcribe }: { readonly session: FeedbackSession; readonly labels?: Partial<FeedbackLabels>; readonly transcribe?: PinTranscribe }) {\n  const state = useExternal(session);\n  const words = withLabels(labels);\n  const bubble = state.bubble;\n  const field = useRef<HTMLTextAreaElement>(null);\n  const [place, setPlace] = useState<CSSProperties | undefined>(undefined);\n  const [, redraw] = useState(0);\n  const [announce, setAnnounce] = useState('');\n  const box = useRef<HTMLDivElement>(null);\n  // The bubble's natural height (its content plus borders), not the height it is clamped to, so it grows back when there is room.\n  const size = (): number | undefined => (box.current ? box.current.scrollHeight + box.current.offsetHeight - box.current.clientHeight : 0) || undefined;\n  useLayoutEffect(() => { if (bubble) setPlace(bubblePlace(bubble.element, size())); }, [bubble?.noteId, bubble?.element]);\n  // Once drawn, place it again with its real height (taller with 44px touch targets and wrapped buttons).\n  useLayoutEffect(() => {\n    if (!bubble || !place || !box.current) return;\n    const next = bubblePlace(bubble.element, size());\n    if (next.top !== place.top || next.left !== place.left) setPlace(next);\n  });\n  useEffect(() => { if (bubble) field.current?.focus({ preventScroll: true }); }, [bubble?.noteId]);\n  useEffect(() => {\n    if (!bubble) return;\n    const view = bubble.element.ownerDocument.defaultView;\n    const follow = () => { setPlace(bubblePlace(bubble.element, size())); redraw(value => value + 1); };\n    view?.addEventListener('scroll', follow, { capture: true, passive: true });\n    view?.addEventListener('resize', follow);\n    return () => { view?.removeEventListener('scroll', follow, { capture: true }); view?.removeEventListener('resize', follow); };\n  }, [bubble?.noteId, bubble?.element]);\n  // A polite live region outlives the bubble, so the cancellation is heard even though the dialog is gone.\n  const cancel = (): void => { session.cancelSelection(); setAnnounce(words.selectionCancelled); };\n  const live = <span data-boring=\"feedback\" data-feedback-ignore=\"\" role=\"status\" aria-live=\"polite\" className=\"boring-feedback-sr\" data-testid=\"feedback-bubble-announce\"\n    style={{ position: 'absolute', width: 1, height: 1, overflow: 'hidden', clip: 'rect(0 0 0 0)', whiteSpace: 'nowrap' }}>{announce}</span>;\n  if (!bubble || state.phase !== 'active') return state.phase === 'active' ? live : null;\n  const onKeyDown = (event: KeyboardEvent<HTMLElement>): void => {\n    if (event.key === 'Enter' && !event.shiftKey && !event.nativeEvent.isComposing && event.target === field.current) { event.preventDefault(); session.saveBubble(); }\n    else if (event.key === 'Escape') { event.preventDefault(); event.stopPropagation(); session.cancelBubble(); }\n  };\n  return <>{live}<Card size=\"sm\" data-boring=\"feedback\" data-feedback-ignore=\"\" role=\"dialog\" aria-label={`Note ${bubble.number}`} data-testid=\"feedback-bubble\" data-note={bubble.number}\n    ref={box} className=\"boring-feedback-bubble\" style={place} onKeyDown={onKeyDown}>\n    <span className=\"boring-feedback-bubble-head\"><span className=\"boring-feedback-pin\" aria-hidden=\"true\">{pinMark(bubble.number)}</span>\n      <span className=\"boring-feedback-bubble-label\" data-testid=\"feedback-bubble-label\">{plainElement(bubble.label, words)}</span></span>\n    <span className=\"boring-feedback-pin-field\">\n      <Textarea ref={field} data-testid=\"feedback-bubble-input\" rows={2} placeholder={words.bubblePlaceholder} aria-label={words.bubblePlaceholder} value={bubble.text}\n        onChange={event => session.setBubbleText(event.target.value)} />\n      {transcribe && <PinMic key={bubble.noteId} session={session} transcribe={transcribe} words={words} />}\n    </span>\n    <span className=\"boring-feedback-bubble-actions\">\n      <Button variant=\"ghost\" className=\"min-h-11 min-w-11\" data-testid=\"feedback-cancel-selection\" onClick={cancel}>{words.cancelSelection}</Button>\n      <Button variant=\"default\" className=\"min-h-11 min-w-11\" data-testid=\"feedback-bubble-save\" onClick={() => session.saveBubble()}>{words.add}</Button>\n    </span>\n  </Card></>;\n}\n\nexport interface FeedbackChipProps {\n  readonly session: FeedbackSession;\n  /** Opens the review on first render (journeys). */\n  readonly defaultOpen?: boolean;\n  /** Offer Copy report in the review: the way to use feedback with no chat and no store. */\n  readonly copy?: boolean;\n}\n\n/** The one composer chip after Done: `💬 Feedback · 3 notes · /settings/:section`. Click opens the review; × discards. */\nexport function FeedbackChip({ session, defaultOpen = false, copy = false }: FeedbackChipProps) {\n  const state = useExternal(session);\n  const [open, setOpen] = useState(defaultOpen);\n  const chip = useRef<HTMLSpanElement>(null);\n  if (state.phase !== 'review') return null;\n  const count = noteCount(state);\n  const pins = emptyPinCount(state);\n  const refusal = state.send.kind !== 'idle' && state.send.kind !== 'sending' && state.send.kind !== 'saved' ? state.send.reason : undefined;\n  return <span ref={chip} data-boring=\"feedback\" data-feedback-ignore=\"\" data-testid=\"feedback-chip\" data-send={state.send.kind} className=\"boring-feedback-chip\">\n    <Button variant=\"outline\" className=\"min-w-0 max-w-full\" data-testid=\"feedback-chip-open\" aria-expanded={open} onClick={() => setOpen(value => !value)}\n      title={refusal ?? 'Review your feedback before sending'}>\n      <span aria-hidden=\"true\">💬</span> Feedback · {plural(count, 'note', 'notes')}{pins ? ` · ${plural(pins, 'pin', 'pins')} to describe` : ''} · <span className=\"boring-feedback-chip-route\">{state.route}</span>\n    </Button>\n    <Button variant=\"ghost\" size=\"icon-sm\" data-testid=\"feedback-chip-discard\" aria-label=\"Discard feedback\" title=\"Discard feedback\" onClick={() => { session.highlight(undefined); session.discard(); }}><XIcon data-icon=\"inline-start\" aria-hidden=\"true\" /></Button>\n    {state.problem && <span className=\"boring-feedback-warning\" role=\"alert\" data-testid=\"feedback-chip-voice\">{state.problem}</span>}\n    {refusal && <span className=\"boring-feedback-warning\" role=\"alert\" data-testid=\"feedback-chip-problem\">{refusal}</span>}\n    {/* In the page's body: the chip may sit in a transformed chat bar, where a fixed panel would not be placed against the viewport. */}\n    {open && createPortal(<FeedbackReview session={session} anchor={chip.current} copy={copy} onClose={() => setOpen(false)} />, chip.current?.ownerDocument.body ?? document.body)}\n  </span>;\n}\n\nfunction reviewPlace(anchor: Element | null): CSSProperties | undefined {\n  if (!anchor) return undefined;\n  const view = anchor.ownerDocument.defaultView;\n  const width = view?.innerWidth ?? 1024, height = view?.innerHeight ?? 768;\n  const rect = anchor.getBoundingClientRect();\n  const panel = Math.min(416, width - 24);\n  return { position: 'fixed', left: Math.min(Math.max(12, rect.left), width - panel - 12), bottom: Math.max(12, height - rect.top + 8), width: panel };\n}\n\n/** The compact review: notes in order, editable and removable; hovering a note highlights its element in the page, or says it is not here. */\nexport function FeedbackReview({ session, anchor = null, copy = false, onClose }: { readonly session: FeedbackSession; readonly anchor?: Element | null; readonly copy?: boolean; readonly onClose: () => void }) {\n  const state = useExternal(session);\n  const [where, setWhere] = useState<Readonly<Record<number, 'shown' | 'not-on-page'>>>({});\n  const [place, setPlace] = useState<CSSProperties | undefined>(undefined);\n  useLayoutEffect(() => { setPlace(reviewPlace(anchor)); }, [anchor]);\n  useEffect(() => () => { session.highlight(undefined); }, [session]);\n  const hover = (id: number | undefined): void => {\n    const result = session.highlight(id);\n    if (id !== undefined && result !== 'none') setWhere(value => ({ ...value, [id]: result }));\n  };\n  const onKeyDown = (event: KeyboardEvent<HTMLElement>): void => { if (event.key === 'Escape') { event.stopPropagation(); onClose(); } };\n  return <Card size=\"sm\" data-boring=\"feedback\" data-feedback-ignore=\"\" role=\"dialog\" aria-label=\"Review feedback\" data-testid=\"feedback-review\" className=\"boring-feedback-review\"\n    style={place} onKeyDown={onKeyDown} onMouseLeave={() => hover(undefined)}>\n    <header className=\"boring-feedback-sheet-header\"><h2>Feedback · {state.route}</h2>\n      <Button variant=\"ghost\" size=\"icon\" aria-label=\"Close review\" title=\"Close review\" data-testid=\"feedback-review-close\" onClick={onClose}><XIcon data-icon=\"inline-start\" aria-hidden=\"true\" /></Button></header>\n    {state.problem && <p className=\"boring-feedback-warning\" role=\"alert\" data-testid=\"feedback-review-problem\">{state.problem}</p>}\n    <ol className=\"boring-feedback-notes\">\n      {state.notes.map(note => <li key={note.id} data-testid=\"feedback-review-note\" data-note={note.number} data-where={where[note.id]}\n        onMouseEnter={() => hover(note.id)} onFocus={() => hover(note.id)}>\n        <span className=\"boring-feedback-note-head\"><span className=\"boring-feedback-pin\" aria-hidden=\"true\">{pinMark(note.number)}</span>\n          <ElementName note={note} />\n          {note.from === 'voice' && <Badge variant=\"secondary\" data-testid=\"feedback-review-voice\">voice</Badge>}\n          {where[note.id] === 'not-on-page' && <Badge variant=\"secondary\" data-testid=\"feedback-review-elsewhere\">not on this page</Badge>}\n          <Button variant=\"ghost\" size=\"icon\" aria-label={`Remove note ${note.number}`} title={`Remove note ${note.number}`} data-testid=\"feedback-review-remove\" onClick={() => session.removeNote(note.id)}><XIcon data-icon=\"inline-start\" aria-hidden=\"true\" /></Button></span>\n        <Textarea rows={2} aria-label={`Note ${note.number}`} data-testid=\"feedback-review-text\" value={note.text} placeholder={note.recorded ? 'Nothing was said here: type a note, or remove the pin' : undefined}\n          onChange={event => session.setNoteText(note.id, event.target.value)} />\n      </li>)}\n    </ol>\n    <label className=\"boring-feedback-field\"><span>General note</span>\n      <Textarea rows={2} data-testid=\"feedback-review-general\" placeholder=\"Anything else? (optional)\" value={state.general} onChange={event => session.setGeneral(event.target.value)} /></label>\n    <p className=\"boring-feedback-meta\">{state.stepCount > 1 ? `${plural(state.stepCount, 'step', 'steps')} recorded between the notes. ` : ''}{copy ? 'Copy the report and paste it anywhere.' : 'Sent with your next message.'}</p>\n    {copy && <div className=\"boring-feedback-actions\">\n      <Button variant=\"default\" data-testid=\"feedback-copy\" onClick={() => { void session.copy(); }}>Copy report</Button></div>}\n    {copy && <p role=\"status\" aria-live=\"polite\" className=\"boring-feedback-status\" data-testid=\"feedback-status\" data-copy={state.copy.kind}>\n      {state.copy.kind === 'copied' ? 'Report copied. Paste it anywhere.' : state.copy.kind === 'manual' ? 'The clipboard is not available here: select the report below and copy it.' : state.copy.kind === 'refused' ? state.copy.reason : ''}</p>}\n    {copy && state.copy.kind === 'manual' && <Textarea readOnly className=\"boring-feedback-manual\" data-testid=\"feedback-manual-copy\" value={state.copy.text} rows={6} onFocus={event => event.currentTarget.select()} />}\n    {copy && state.copy.kind === 'copied' && <details className=\"boring-feedback-copied\"><summary>Copied report</summary><pre data-testid=\"feedback-copy-text\">{state.copy.text}</pre></details>}\n  </Card>;\n}\n\n/**\n * A note's element as one calm line: the readable name (semibold) and the file basename (muted, monospace), the full path in the\n * tooltip. The same reading as the pi-chat feedback card's element line (`readableElement` from `@hachej/boring-feedback/format`).\n */\nexport function ElementName({ note }: { readonly note: SessionNote }) {\n  const readable = note.fallback ? readableElement(note.fallback, note.source) : { name: note.label };\n  return <span className=\"boring-feedback-element\" data-testid=\"feedback-review-element\" title={'path' in readable && readable.path ? readable.path : note.label}>\n    <span className=\"boring-feedback-element-name\" data-testid=\"feedback-review-name\">{readable.name}</span>\n    {'file' in readable && readable.file && <span className=\"boring-feedback-element-file\" data-testid=\"feedback-review-file\">{readable.file}</span>}\n  </span>;\n}\n\n/** What `useComposerFeedback` returns: the structural shape of pi-chat's `ComposerFeedback`. */\nexport interface ComposerFeedbackProp {\n  readonly annotate: () => void;\n  readonly active: boolean;\n  readonly count: number;\n  readonly clear: () => void;\n  readonly attach: (text: string) => Promise<{ readonly kind: 'ok'; readonly text: string } | { readonly kind: 'refused'; readonly reason: string }>;\n  readonly sent: () => void;\n}\n\n/** A Markdown fence longer than any backtick run in the text. */\nfunction fenced(text: string): string {\n  const longest = Math.max(0, ...[...text.matchAll(/`+/g)].map(match => match[0].length));\n  const fence = '`'.repeat(Math.max(3, longest + 1));\n  return `${fence}markdown\\n${text.endsWith('\\n') ? text : `${text}\\n`}${fence}`;\n}\n\n/** Touch or a compact screen: the panel covers the app and there is no hover, so annotating is point mode (use the app, then point). */\nfunction pointsInstead(): boolean {\n  return globalThis.matchMedia?.('(pointer: coarse)').matches === true || (globalThis.innerWidth ?? 1024) < 768;\n}\n\n/**\n * Starts (or resumes) annotating in either mode, with Esc as a way out. The session swallows Esc on the page (it only closes a pin), so\n * this listens on the window's capture phase BEFORE the session starts, and ends the mode (Done: the notes wait for Send) when no pin is\n * open. From the review, `resume` keeps the notes, anchors and save guards: a second round adds to the same draft.\n */\nfunction startAnnotating(session: FeedbackSession, mode: 'point' | undefined = pointsInstead() ? 'point' : undefined, fresh = true): void {\n  if (fresh) sentInRound.delete(session);\n  const view = globalThis.window;\n  const onKey = (event: globalThis.KeyboardEvent): void => {\n    // Esc that ends annotating is spent: a host layer around the composer (a panel that closes on Esc) must not also react to it.\n    if (event.key === 'Escape' && !session.getSnapshot().bubble) { event.preventDefault(); event.stopPropagation(); void session.done(); }\n  };\n  view?.addEventListener('keydown', onKey, { capture: true });\n  session.resume(mode ? { mode } : {});\n  const stop = session.subscribe(() => {\n    if (session.getSnapshot().phase === 'active') return;\n    view?.removeEventListener('keydown', onKey, { capture: true });\n    stop();\n  });\n}\n\n/**\n * The composer's `feedback` prop for a session: ONE annotate toggle (targeting with a hover highlight; point mode on touch and compact\n * screens, and again after Esc to add more), a count of the notes taken, and Send attaching them: a saved report as its `@` mention (the host's mention resolver inlines\n * the stored report with the person's access), otherwise the rendered report inline in a fenced block. Pair it with `NoteBubble`.\n */\nexport function useComposerFeedback(session: FeedbackSession | undefined): ComposerFeedbackProp | undefined {\n  const state = useSyncState(session);\n  if (!session || !state) return undefined;\n  const open = state.phase === 'active' || state.phase === 'processing';\n  return {\n    annotate: () => {\n      const phase = session.getSnapshot().phase;\n      if (phase === 'active') void session.done();\n      else if (phase === 'idle' || phase === 'review') startAnnotating(session);\n    },\n    active: open,\n    // A note being typed in the pin counts: Send saves it.\n    count: noteCount(state) + (state.bubble?.fresh && state.bubble.text.trim() ? 1 : 0),\n    clear: () => { session.highlight(undefined); session.discard(); },\n    attach: async text => {\n      // Send while annotating ends it first: the pin being typed is kept.\n      if (session.getSnapshot().phase === 'active') await session.done();\n      const attached = await session.attach();\n      if (attached.kind === 'refused') return attached;\n      const body = attached.kind === 'mention' ? `@${attached.path}` : fenced(attached.text);\n      return { kind: 'ok', text: text.trim() ? `${text.trimEnd()}\\n\\n${body}` : body };\n    },\n    sent: () => session.sent(),\n  };\n}\n\n/** Notes sent one by one in the current round of comment mode (`useSendEachNote`), for the banner; a new round starts at zero. */\nconst sentInRound = new WeakMap<FeedbackSession, number>();\nexport const notesSent = (session: FeedbackSession): number => sentInRound.get(session) ?? 0;\n\n/**\n * Each note goes to the chat the moment it is added: its element and text as one message (`send`, the chat's follow-up send), and\n * comment mode stays on for the next note. Nothing waits in a hidden batch, and the agent's reply follows in the conversation. Without\n * `send`, the notes wait for the person's next message as before. A refused report or a failed send stays in the review, where the composer shows it.\n */\nexport function useSendEachNote(session: FeedbackSession | undefined, send: ((text: string) => Promise<unknown>) | undefined): void {\n  const state = useSyncState(session);\n  const busy = useRef(false);\n  useEffect(() => {\n    if (!session || !send || !state || busy.current) return;\n    if (state.phase !== 'active' || state.bubble || !state.notes.some(note => note.text.trim())) return;\n    busy.current = true;\n    const mode = state.mode === 'point' ? 'point' : undefined;\n    void (async () => {\n      let again = false;\n      try {\n        await session.done();\n        const attached = await session.attach();\n        if (attached.kind === 'refused') return;\n        const submission = await send(attached.kind === 'mention' ? `@${attached.path}` : fenced(attached.text)).catch(() => undefined);\n        if (submission === false || submission === undefined || submission === null) return;\n        sentInRound.set(session, notesSent(session) + noteCount(session.getSnapshot()));\n        session.sent();\n        again = true;\n      } finally {\n        busy.current = false;\n        if (again) startAnnotating(session, mode, false);\n      }\n    })();\n  }, [session, send, state]);\n}\n\nconst NO_STATE = { getSnapshot: () => undefined, subscribe: () => () => {} };\nfunction useSyncState(session: FeedbackSession | undefined): FeedbackSessionSnapshot | undefined {\n  return useExternal<FeedbackSessionSnapshot | undefined>(session ?? NO_STATE);\n}\n\n/** What `usePointComments` returns: the structural shape of the maquette viewer's `MaquetteComments` (any viewer may take it). */\nexport interface PointCommentsProp {\n  /** A host-owned proxy element for an opaque frame pick, checked by the session's root and privacy policy. */\n  readonly pick: (element: Element) => void;\n  readonly reposition: () => void;\n  /** Clicks are currently captured, false during Use app or processing. */\n  readonly picking: boolean;\n  /** The session is annotating now (point mode or feedback mode). */\n  readonly active: boolean;\n  /** Point mode on the page, keeping the notes already taken (from the review too); Done when it is on. Esc ends it like the composer's toggle. */\n  readonly point: () => void;\n  /** Every pin with a marked element: its number and the `data-feedback-id` it sits in (`SessionNote.feedbackId`). */\n  readonly pins: readonly { readonly number: number; readonly target: string }[];\n}\n\n/**\n * Comment pins for a viewer inside the page (the maquette viewer's `comments`): the same session, notes, bubble, review and Send as the\n * composer's toggle, entered in point mode from the viewer's own icon. A viewer marks its parts with `data-feedback-id` and matches the\n * pins on them. Undefined without a session, so the viewer shows no icon.\n */\nexport function usePointComments(session: FeedbackSession | undefined): PointCommentsProp | undefined {\n  const state = useSyncState(session);\n  // One object per session state, so a host that puts it in a memoized kind list re-renders only when the pins or the mode change.\n  return useMemo(() => !session || !state ? undefined : {\n    active: state.phase === 'active' || state.phase === 'processing',\n    pick: session.pick,\n    reposition: session.reposition,\n    picking: state.phase === 'active' && !state.using,\n    point: () => {\n      const phase = session.getSnapshot().phase;\n      if (phase === 'active') void session.done();\n      else if (phase === 'idle' || phase === 'review') startAnnotating(session, 'point');\n    },\n    pins: state.notes.flatMap(note => note.feedbackId ? [{ number: note.number, target: note.feedbackId }] : []),\n  }, [session, state]);\n}\n",
+      "content": "// The feedback session's look (FEEDBACK.md, \"UX\"): the note pin beside a picked element (NoteBubble: a text field with a mic inside it),\n// the slim bar and the chip with its review (optional, for hosts with no chat). Everything they show and do is the headless\n// `createFeedbackSession` from `@hachej/boring-feedback/ui` (hover labels, pins, steps, the draft and Send come from there, through the\n// privacy policy); this file is how it looks. `useComposerFeedback` adapts a session to the chat composer's optional `feedback` prop\n// (registry/pi-chat): ONE annotate toggle and a count chip, structurally, so neither item imports the other.\nimport { useEffect, useLayoutEffect, useMemo, useRef, useState, type CSSProperties, type KeyboardEvent } from 'react';\nimport { createPortal } from 'react-dom';\nimport { MicIcon, SquareIcon, XIcon } from 'lucide-react';\nimport { Button } from '@/components/ui/button';\nimport { Toggle } from '@/components/ui/toggle';\nimport { Badge } from '@/components/ui/badge';\nimport { Card } from '@/components/ui/card';\nimport { Textarea } from '@/components/ui/textarea';\nimport { readableElement } from '@hachej/boring-feedback/format';\nimport { createVoiceCapture, type VoiceCapture } from '@hachej/boring-feedback/page';\nimport { pinMark, type FeedbackSession, type FeedbackSessionSnapshot, type SessionNote } from '@hachej/boring-feedback/ui';\nimport { useHoldToRecord } from '../pi-chat-voice/use-hold-to-record';\nimport { useExternal } from './use-external';\nimport { plainElement, withLabels, type FeedbackLabels } from './feedback-labels';\n\nconst plural = (count: number, one: string, many: string): string => `${count} ${count === 1 ? one : many}`;\n/** Notes the chip and the bar count: every note that says something (not a pin still being typed), plus the general note. */\nexport function noteCount(state: FeedbackSessionSnapshot): number {\n  return state.notes.filter(note => note.text.trim()).length + (state.general.trim() ? 1 : 0);\n}\n\nexport interface FeedbackBarProps {\n  readonly session: FeedbackSession;\n  readonly className?: string;\n  /** Docked under the chat composer (the composer's `feedback.bar`) instead of floating at the top of the page. */\n  readonly docked?: boolean;\n}\n\n/** Pins dropped while recording that have no note yet (nothing transcribed for them, or transcription failed). */\nexport function emptyPinCount(state: FeedbackSessionSnapshot): number {\n  return state.notes.filter(note => note.recorded && !note.text.trim()).length;\n}\n\n/** `mm:ss` since `since` (ms), for the recording timer. */\nexport function elapsed(ms: number): string {\n  const seconds = Math.max(0, Math.floor(ms / 1000));\n  return `${String(Math.floor(seconds / 60)).padStart(2, '0')}:${String(seconds % 60).padStart(2, '0')}`;\n}\n\n/** The running time of a recording, from when the bar saw it start; 00:00 when not recording. */\nfunction useRecordingTime(recording: boolean): string {\n  const [since, setSince] = useState<number | undefined>(undefined);\n  const [, tick] = useState(0);\n  useEffect(() => {\n    if (!recording) { setSince(undefined); return; }\n    setSince(Date.now());\n    const timer = setInterval(() => tick(value => value + 1), 500);\n    return () => clearInterval(timer);\n  }, [recording]);\n  return elapsed(since === undefined ? 0 : Date.now() - since);\n}\n\nfunction barHint(state: FeedbackSessionSnapshot): string {\n  if (state.phase === 'processing') return state.transcribing ? 'Transcribing…' : 'Preparing your feedback…';\n  if (state.problem) return state.problem;\n  if (state.voice.kind === 'starting') return 'Allow the microphone if your browser asks…';\n  if (state.voice.kind === 'recording') return state.using ? 'Recording — using the app' : 'Recording — point and talk';\n  return state.using ? 'Using the app: your clicks are recorded as steps' : 'Click what you want to comment on';\n}\n\n/**\n * Feedback mode's bar: `● Feedback · N notes · 🎙 Record · Use app · Done · ✕`. While recording: a red dot, the\n * running time, \"Recording — point and talk\" and Stop. A refused microphone is said in the bar itself, never only in a tooltip.\n */\nexport function FeedbackBar({ session, className, docked = false }: FeedbackBarProps) {\n  const state = useExternal(session);\n  const recording = state.voice.kind === 'recording';\n  const time = useRecordingTime(recording && (state.phase === 'active' || state.phase === 'processing'));\n  if (state.phase !== 'active' && state.phase !== 'processing') return null;\n  const processing = state.phase === 'processing';\n  const pins = emptyPinCount(state);\n  const voiceProblem = state.voice.kind === 'refused' ? state.voice : undefined;\n  return <Card size=\"sm\" data-boring=\"feedback\" data-feedback-ignore=\"\" role=\"toolbar\" aria-label=\"Feedback mode\" data-testid=\"feedback-bar\" data-docked={docked ? 'true' : 'false'}\n    data-using={state.using ? 'true' : 'false'} data-recording={recording ? 'true' : 'false'} data-transcribing={state.transcribing ? 'true' : 'false'}\n    className={['boring-feedback-bar', className].filter(Boolean).join(' ')}\n    onKeyDown={event => { if (event.key === 'Escape' && state.bubble) { event.stopPropagation(); session.cancelBubble(); } }}>\n    <span className=\"boring-feedback-bar-title\">Feedback</span>\n    <span className=\"boring-feedback-bar-meta\" data-testid=\"feedback-bar-count\">{plural(noteCount(state), 'note', 'notes')}{pins ? ` · ${plural(pins, 'pin', 'pins')}` : ''}</span>\n    {state.voiceAvailable && <Toggle data-testid=\"feedback-voice\" pressed={recording}\n      disabled={processing || state.voice.kind === 'starting' || state.voice.kind === 'stopping'} title={recording ? 'Stop recording' : 'Record your voice while you point: each click drops a pin, what you say becomes its note'}\n      onPressedChange={() => { void session.toggleVoice(); }}>\n      {recording ? <><SquareIcon data-icon=\"inline-start\" aria-hidden=\"true\" />Stop</> : <><MicIcon data-icon=\"inline-start\" aria-hidden=\"true\" />{state.voice.kind === 'starting' ? 'Starting…' : state.voice.kind === 'stopping' ? 'Stopping…' : 'Record'}</>}\n    </Toggle>}\n    {recording && <Badge variant=\"destructive\" role=\"status\" data-testid=\"feedback-recording\">\n      <span className=\"boring-feedback-timer\" data-testid=\"feedback-recording-time\">{time}</span></Badge>}\n    <span className=\"boring-feedback-hint\" role=\"status\" aria-live=\"polite\" data-testid=\"feedback-bar-hint\">{barHint(state)}</span>\n    {voiceProblem && <span className=\"boring-feedback-voice-problem\" role=\"alert\" data-testid=\"feedback-voice-problem\" data-code={voiceProblem.code}>{voiceProblem.reason}</span>}\n    {!processing && <Toggle data-testid=\"feedback-use-app\" pressed={state.useToggle} onPressedChange={pressed => session.setUseToggle(pressed)}>Use app</Toggle>}\n    <Button variant=\"default\" data-testid=\"feedback-done\" disabled={processing} onClick={() => { void session.done(); }}>Done</Button>\n    <Button variant=\"ghost\" size=\"icon\" data-testid=\"feedback-discard\" aria-label=\"Discard feedback\" title=\"Discard feedback\" disabled={processing} onClick={() => session.discard()}><XIcon data-icon=\"inline-start\" aria-hidden=\"true\" /></Button>\n  </Card>;\n}\n\nconst BUBBLE_WIDTH = 280;\n/** Pixels at the bottom of the viewport taken by comment mode's banner on a phone (CommentBanner, `data-feedback-point-bar=\"bottom\"`), plus a gap; 0 without it. */\nexport function pointBarInset(document: Document): number {\n  const bar = document.querySelector('[data-feedback-point-bar=\"bottom\"]');\n  const height = document.defaultView?.innerHeight ?? 768;\n  return bar ? Math.max(0, height - bar.getBoundingClientRect().top + 8) : 0;\n}\n\n/**\n * Beside the element: below it when the bubble (`size`, its measured height once drawn) fits above point mode's bar (if any), else\n * above it, else as low as it fits. Every branch is clamped to the space above the bar, so the bubble never covers it; a bubble taller\n * than that space scrolls inside it.\n */\nfunction bubblePlace(element: Element, size = 120): CSSProperties {\n  const view = element.ownerDocument.defaultView;\n  const width = view?.innerWidth ?? 1024, height = (view?.innerHeight ?? 768) - pointBarInset(element.ownerDocument);\n  const rect = element.getBoundingClientRect();\n  const left = Math.min(Math.max(8, rect.left), Math.max(8, width - BUBBLE_WIDTH - 8));\n  const below = rect.bottom + 8;\n  const above = rect.top - size - 8;\n  const lowest = Math.max(8, height - size);\n  const top = Math.min(below + size <= height ? below : above >= 8 ? above : lowest, lowest);\n  return { position: 'fixed', top, left, width: Math.min(BUBBLE_WIDTH, width - 16), maxHeight: Math.max(0, height - top), overflowY: 'auto', boxSizing: 'border-box' };\n}\n\ntype PinVoice = 'idle' | 'starting' | 'recording' | 'transcribing';\n\n/**\n * The mic inside the pin's field, held like the chat's voice message (`useHoldToRecord`, the same gesture policy as the composer and the\n * shell): press and hold to talk (Space or Enter from the keyboard), release and the transcript is added to the note and the note is kept\n * (with `useSendEachNote`, sent at once). A slide off the button, Escape or a hidden page drops the recording. A refused microphone, nothing\n * heard or a rejected transcription is said under the field and never touches the typed text. One capture (`createVoiceCapture`) per pin.\n */\nfunction PinMic({ session, transcribe, words }: { readonly session: FeedbackSession; readonly transcribe: PinTranscribe; readonly words: FeedbackLabels }) {\n  const [phase, setPhase] = useState<PinVoice>('idle');\n  const [problem, setProblem] = useState<string | undefined>(undefined);\n  const capture = useRef<VoiceCapture | null>(null);\n  const run = useRef(0);\n  const work = useRef<AbortController | null>(null);\n  // Let go before the microphone was ready: the recording ends as soon as it starts.\n  const released = useRef(false);\n  capture.current ??= createVoiceCapture();\n  // A closed pin releases the microphone and drops a transcription still in flight.\n  useEffect(() => () => { run.current += 1; capture.current?.cancel(); work.current?.abort(); }, []);\n  const finish = async (): Promise<void> => {\n    const attempt = run.current;\n    setPhase('transcribing');\n    const recording = await capture.current!.stop().catch(() => null);\n    if (attempt !== run.current) return;\n    if (!recording) { setPhase('idle'); setProblem(words.voiceNothing); return; }\n    const abort = new AbortController();\n    work.current = abort;\n    try {\n      const spoken = (await transcribe(recording.audio, abort.signal)).trim();\n      if (attempt !== run.current) return;\n      if (!spoken) { setProblem(words.voiceNothing); return; }\n      // Appended to what is typed NOW (the person may have kept typing), never replacing it.\n      const typed = session.getSnapshot().bubble?.text ?? '';\n      session.setBubbleText(`${typed}${typed === '' || /\\s$/.test(typed) ? '' : ' '}${spoken}`);\n      session.saveBubble();\n    } catch { if (attempt === run.current) setProblem(words.voiceFailed); }\n    finally { if (work.current === abort) work.current = null; if (attempt === run.current) setPhase('idle'); }\n  };\n  const hold = useHoldToRecord({\n    // Called straight from the press, so the browser ties the permission prompt to the person's gesture.\n    start: () => {\n      const attempt = ++run.current;\n      released.current = false;\n      setProblem(undefined); setPhase('starting');\n      void capture.current!.start().then(result => {\n        if (attempt !== run.current) return;\n        if (result.kind === 'refused') { setPhase('idle'); setProblem(result.reason); return; }\n        setPhase('recording');\n        if (released.current) void finish();\n      });\n    },\n    finish: () => { if (phase === 'recording') void finish(); else released.current = true; },\n    cancel: () => { run.current += 1; capture.current?.cancel(); setPhase('idle'); },\n  }, phase === 'transcribing');\n  const recording = phase === 'recording';\n  return <>\n    <Button {...hold} variant=\"ghost\" size=\"icon\" className=\"boring-feedback-pin-mic min-h-11 min-w-11 touch-none select-none\" data-testid=\"feedback-bubble-mic\" data-state={phase}\n      aria-pressed={recording || phase === 'starting'} aria-label={recording ? words.voiceStop : words.voiceRecord} title={recording ? words.voiceStop : words.voiceRecord} disabled={phase === 'transcribing'}>\n      {phase === 'transcribing' ? <span role=\"status\" aria-label={words.voiceTranscribing}>…</span>\n        : recording ? <SquareIcon data-icon=\"inline-start\" aria-hidden=\"true\" /> : <MicIcon data-icon=\"inline-start\" aria-hidden=\"true\" />}\n    </Button>\n    {problem && <span className=\"boring-feedback-voice-problem\" role=\"alert\" data-testid=\"feedback-bubble-voice-problem\">{problem}</span>}\n  </>;\n}\n\n/** Turns a recording into text (`signal` aborts when the pin closes); a rejection keeps what was typed. */\nexport type PinTranscribe = (audio: Blob, signal: AbortSignal) => Promise<string>;\n\n/**\n * The pin beside a picked element: a text field with a mic inside it, \"Add note\" (Enter) and Cancel (Esc). Enter saves, Shift-Enter for a\n * new line, Esc discards the pin. The element is named in plain words (`plainElement`). On a phone it keeps clear of the comment banner. `transcribe` turns the mic's recording into text; without it there is no mic.\n */\nexport function NoteBubble({ session, labels, transcribe }: { readonly session: FeedbackSession; readonly labels?: Partial<FeedbackLabels>; readonly transcribe?: PinTranscribe }) {\n  const state = useExternal(session);\n  const words = withLabels(labels);\n  const bubble = state.bubble;\n  const field = useRef<HTMLTextAreaElement>(null);\n  const [place, setPlace] = useState<CSSProperties | undefined>(undefined);\n  const [, redraw] = useState(0);\n  const [announce, setAnnounce] = useState('');\n  const box = useRef<HTMLDivElement>(null);\n  // The bubble's natural height (its content plus borders), not the height it is clamped to, so it grows back when there is room.\n  const size = (): number | undefined => (box.current ? box.current.scrollHeight + box.current.offsetHeight - box.current.clientHeight : 0) || undefined;\n  useLayoutEffect(() => { if (bubble) setPlace(bubblePlace(bubble.element, size())); }, [bubble?.noteId, bubble?.element]);\n  // Once drawn, place it again with its real height (taller with 44px touch targets and wrapped buttons).\n  useLayoutEffect(() => {\n    if (!bubble || !place || !box.current) return;\n    const next = bubblePlace(bubble.element, size());\n    if (next.top !== place.top || next.left !== place.left) setPlace(next);\n  });\n  useEffect(() => { if (bubble) field.current?.focus({ preventScroll: true }); }, [bubble?.noteId]);\n  useEffect(() => {\n    if (!bubble) return;\n    const view = bubble.element.ownerDocument.defaultView;\n    const follow = () => { setPlace(bubblePlace(bubble.element, size())); redraw(value => value + 1); };\n    view?.addEventListener('scroll', follow, { capture: true, passive: true });\n    view?.addEventListener('resize', follow);\n    return () => { view?.removeEventListener('scroll', follow, { capture: true }); view?.removeEventListener('resize', follow); };\n  }, [bubble?.noteId, bubble?.element]);\n  // A polite live region outlives the bubble, so the cancellation is heard even though the dialog is gone.\n  const cancel = (): void => { session.cancelSelection(); setAnnounce(words.selectionCancelled); };\n  const live = <span data-boring=\"feedback\" data-feedback-ignore=\"\" role=\"status\" aria-live=\"polite\" className=\"boring-feedback-sr\" data-testid=\"feedback-bubble-announce\"\n    style={{ position: 'absolute', width: 1, height: 1, overflow: 'hidden', clip: 'rect(0 0 0 0)', whiteSpace: 'nowrap' }}>{announce}</span>;\n  if (!bubble || state.phase !== 'active') return state.phase === 'active' ? live : null;\n  const onKeyDown = (event: KeyboardEvent<HTMLElement>): void => {\n    if (event.key === 'Enter' && !event.shiftKey && !event.nativeEvent.isComposing && event.target === field.current) { event.preventDefault(); session.saveBubble(); }\n    else if (event.key === 'Escape') { event.preventDefault(); event.stopPropagation(); session.cancelBubble(); }\n  };\n  return <>{live}<Card size=\"sm\" data-boring=\"feedback\" data-feedback-ignore=\"\" role=\"dialog\" aria-label={`Note ${bubble.number}`} data-testid=\"feedback-bubble\" data-note={bubble.number}\n    ref={box} className=\"boring-feedback-bubble\" style={place} onKeyDown={onKeyDown}>\n    <span className=\"boring-feedback-bubble-head\"><span className=\"boring-feedback-pin\" aria-hidden=\"true\">{pinMark(bubble.number)}</span>\n      <span className=\"boring-feedback-bubble-label\" data-testid=\"feedback-bubble-label\">{plainElement(bubble.label, words)}</span></span>\n    <span className=\"boring-feedback-pin-field\">\n      <Textarea ref={field} data-testid=\"feedback-bubble-input\" rows={2} placeholder={words.bubblePlaceholder} aria-label={words.bubblePlaceholder} value={bubble.text}\n        onChange={event => session.setBubbleText(event.target.value)} />\n      {transcribe && <PinMic key={bubble.noteId} session={session} transcribe={transcribe} words={words} />}\n    </span>\n    <span className=\"boring-feedback-bubble-actions\">\n      <Button variant=\"ghost\" className=\"min-h-11 min-w-11\" data-testid=\"feedback-cancel-selection\" onClick={cancel}>{words.cancelSelection}</Button>\n      <Button variant=\"default\" className=\"min-h-11 min-w-11\" data-testid=\"feedback-bubble-save\" onClick={() => session.saveBubble()}>{words.add}</Button>\n    </span>\n  </Card></>;\n}\n\nexport interface FeedbackChipProps {\n  readonly session: FeedbackSession;\n  /** Opens the review on first render (journeys). */\n  readonly defaultOpen?: boolean;\n  /** Offer Copy report in the review: the way to use feedback with no chat and no store. */\n  readonly copy?: boolean;\n}\n\n/** The one composer chip after Done: `💬 Feedback · 3 notes · /settings/:section`. Click opens the review; × discards. */\nexport function FeedbackChip({ session, defaultOpen = false, copy = false }: FeedbackChipProps) {\n  const state = useExternal(session);\n  const [open, setOpen] = useState(defaultOpen);\n  const chip = useRef<HTMLSpanElement>(null);\n  if (state.phase !== 'review') return null;\n  const count = noteCount(state);\n  const pins = emptyPinCount(state);\n  const refusal = state.send.kind !== 'idle' && state.send.kind !== 'sending' && state.send.kind !== 'saved' ? state.send.reason : undefined;\n  return <span ref={chip} data-boring=\"feedback\" data-feedback-ignore=\"\" data-testid=\"feedback-chip\" data-send={state.send.kind} className=\"boring-feedback-chip\">\n    <Button variant=\"outline\" className=\"min-w-0 max-w-full\" data-testid=\"feedback-chip-open\" aria-expanded={open} onClick={() => setOpen(value => !value)}\n      title={refusal ?? 'Review your feedback before sending'}>\n      <span aria-hidden=\"true\">💬</span> Feedback · {plural(count, 'note', 'notes')}{pins ? ` · ${plural(pins, 'pin', 'pins')} to describe` : ''} · <span className=\"boring-feedback-chip-route\">{state.route}</span>\n    </Button>\n    <Button variant=\"ghost\" size=\"icon-sm\" data-testid=\"feedback-chip-discard\" aria-label=\"Discard feedback\" title=\"Discard feedback\" onClick={() => { session.highlight(undefined); session.discard(); }}><XIcon data-icon=\"inline-start\" aria-hidden=\"true\" /></Button>\n    {state.problem && <span className=\"boring-feedback-warning\" role=\"alert\" data-testid=\"feedback-chip-voice\">{state.problem}</span>}\n    {refusal && <span className=\"boring-feedback-warning\" role=\"alert\" data-testid=\"feedback-chip-problem\">{refusal}</span>}\n    {/* In the page's body: the chip may sit in a transformed chat bar, where a fixed panel would not be placed against the viewport. */}\n    {open && createPortal(<FeedbackReview session={session} anchor={chip.current} copy={copy} onClose={() => setOpen(false)} />, chip.current?.ownerDocument.body ?? document.body)}\n  </span>;\n}\n\nfunction reviewPlace(anchor: Element | null): CSSProperties | undefined {\n  if (!anchor) return undefined;\n  const view = anchor.ownerDocument.defaultView;\n  const width = view?.innerWidth ?? 1024, height = view?.innerHeight ?? 768;\n  const rect = anchor.getBoundingClientRect();\n  const panel = Math.min(416, width - 24);\n  return { position: 'fixed', left: Math.min(Math.max(12, rect.left), width - panel - 12), bottom: Math.max(12, height - rect.top + 8), width: panel };\n}\n\n/** The compact review: notes in order, editable and removable; hovering a note highlights its element in the page, or says it is not here. */\nexport function FeedbackReview({ session, anchor = null, copy = false, onClose }: { readonly session: FeedbackSession; readonly anchor?: Element | null; readonly copy?: boolean; readonly onClose: () => void }) {\n  const state = useExternal(session);\n  const [where, setWhere] = useState<Readonly<Record<number, 'shown' | 'not-on-page'>>>({});\n  const [place, setPlace] = useState<CSSProperties | undefined>(undefined);\n  useLayoutEffect(() => { setPlace(reviewPlace(anchor)); }, [anchor]);\n  useEffect(() => () => { session.highlight(undefined); }, [session]);\n  const hover = (id: number | undefined): void => {\n    const result = session.highlight(id);\n    if (id !== undefined && result !== 'none') setWhere(value => ({ ...value, [id]: result }));\n  };\n  const onKeyDown = (event: KeyboardEvent<HTMLElement>): void => { if (event.key === 'Escape') { event.stopPropagation(); onClose(); } };\n  return <Card size=\"sm\" data-boring=\"feedback\" data-feedback-ignore=\"\" role=\"dialog\" aria-label=\"Review feedback\" data-testid=\"feedback-review\" className=\"boring-feedback-review\"\n    style={place} onKeyDown={onKeyDown} onMouseLeave={() => hover(undefined)}>\n    <header className=\"boring-feedback-sheet-header\"><h2>Feedback · {state.route}</h2>\n      <Button variant=\"ghost\" size=\"icon\" aria-label=\"Close review\" title=\"Close review\" data-testid=\"feedback-review-close\" onClick={onClose}><XIcon data-icon=\"inline-start\" aria-hidden=\"true\" /></Button></header>\n    {state.problem && <p className=\"boring-feedback-warning\" role=\"alert\" data-testid=\"feedback-review-problem\">{state.problem}</p>}\n    <ol className=\"boring-feedback-notes\">\n      {state.notes.map(note => <li key={note.id} data-testid=\"feedback-review-note\" data-note={note.number} data-where={where[note.id]}\n        onMouseEnter={() => hover(note.id)} onFocus={() => hover(note.id)}>\n        <span className=\"boring-feedback-note-head\"><span className=\"boring-feedback-pin\" aria-hidden=\"true\">{pinMark(note.number)}</span>\n          <ElementName note={note} />\n          {note.from === 'voice' && <Badge variant=\"secondary\" data-testid=\"feedback-review-voice\">voice</Badge>}\n          {where[note.id] === 'not-on-page' && <Badge variant=\"secondary\" data-testid=\"feedback-review-elsewhere\">not on this page</Badge>}\n          <Button variant=\"ghost\" size=\"icon\" aria-label={`Remove note ${note.number}`} title={`Remove note ${note.number}`} data-testid=\"feedback-review-remove\" onClick={() => session.removeNote(note.id)}><XIcon data-icon=\"inline-start\" aria-hidden=\"true\" /></Button></span>\n        <Textarea rows={2} aria-label={`Note ${note.number}`} data-testid=\"feedback-review-text\" value={note.text} placeholder={note.recorded ? 'Nothing was said here: type a note, or remove the pin' : undefined}\n          onChange={event => session.setNoteText(note.id, event.target.value)} />\n      </li>)}\n    </ol>\n    <label className=\"boring-feedback-field\"><span>General note</span>\n      <Textarea rows={2} data-testid=\"feedback-review-general\" placeholder=\"Anything else? (optional)\" value={state.general} onChange={event => session.setGeneral(event.target.value)} /></label>\n    <p className=\"boring-feedback-meta\">{state.stepCount > 1 ? `${plural(state.stepCount, 'step', 'steps')} recorded between the notes. ` : ''}{copy ? 'Copy the report and paste it anywhere.' : 'Sent with your next message.'}</p>\n    {copy && <div className=\"boring-feedback-actions\">\n      <Button variant=\"default\" data-testid=\"feedback-copy\" onClick={() => { void session.copy(); }}>Copy report</Button></div>}\n    {copy && <p role=\"status\" aria-live=\"polite\" className=\"boring-feedback-status\" data-testid=\"feedback-status\" data-copy={state.copy.kind}>\n      {state.copy.kind === 'copied' ? 'Report copied. Paste it anywhere.' : state.copy.kind === 'manual' ? 'The clipboard is not available here: select the report below and copy it.' : state.copy.kind === 'refused' ? state.copy.reason : ''}</p>}\n    {copy && state.copy.kind === 'manual' && <Textarea readOnly className=\"boring-feedback-manual\" data-testid=\"feedback-manual-copy\" value={state.copy.text} rows={6} onFocus={event => event.currentTarget.select()} />}\n    {copy && state.copy.kind === 'copied' && <details className=\"boring-feedback-copied\"><summary>Copied report</summary><pre data-testid=\"feedback-copy-text\">{state.copy.text}</pre></details>}\n  </Card>;\n}\n\n/**\n * A note's element as one calm line: the readable name (semibold) and the file basename (muted, monospace), the full path in the\n * tooltip. The same reading as the pi-chat feedback card's element line (`readableElement` from `@hachej/boring-feedback/format`).\n */\nexport function ElementName({ note }: { readonly note: SessionNote }) {\n  const readable = note.fallback ? readableElement(note.fallback, note.source) : { name: note.label };\n  return <span className=\"boring-feedback-element\" data-testid=\"feedback-review-element\" title={'path' in readable && readable.path ? readable.path : note.label}>\n    <span className=\"boring-feedback-element-name\" data-testid=\"feedback-review-name\">{readable.name}</span>\n    {'file' in readable && readable.file && <span className=\"boring-feedback-element-file\" data-testid=\"feedback-review-file\">{readable.file}</span>}\n  </span>;\n}\n\n/** What `useComposerFeedback` returns: the structural shape of pi-chat's `ComposerFeedback`. */\nexport interface ComposerFeedbackProp {\n  readonly annotate: () => void;\n  readonly active: boolean;\n  readonly count: number;\n  readonly clear: () => void;\n  readonly attach: (text: string) => Promise<{ readonly kind: 'ok'; readonly text: string } | { readonly kind: 'refused'; readonly reason: string }>;\n  readonly sent: () => void;\n}\n\n/** A Markdown fence longer than any backtick run in the text. */\nfunction fenced(text: string): string {\n  const longest = Math.max(0, ...[...text.matchAll(/`+/g)].map(match => match[0].length));\n  const fence = '`'.repeat(Math.max(3, longest + 1));\n  return `${fence}markdown\\n${text.endsWith('\\n') ? text : `${text}\\n`}${fence}`;\n}\n\n/** Touch or a compact screen: the panel covers the app and there is no hover, so annotating is point mode (use the app, then point). */\nfunction pointsInstead(): boolean {\n  return globalThis.matchMedia?.('(pointer: coarse)').matches === true || (globalThis.innerWidth ?? 1024) < 768;\n}\n\n/**\n * Starts (or resumes) annotating in either mode, with Esc as a way out. The session swallows Esc on the page (it only closes a pin), so\n * this listens on the window's capture phase BEFORE the session starts, and ends the mode (Done: the notes wait for Send) when no pin is\n * open. From the review, `resume` keeps the notes, anchors and save guards: a second round adds to the same draft.\n */\nfunction startAnnotating(session: FeedbackSession, mode: 'point' | undefined = pointsInstead() ? 'point' : undefined, fresh = true): void {\n  if (fresh) sentInRound.delete(session);\n  const view = globalThis.window;\n  const onKey = (event: globalThis.KeyboardEvent): void => {\n    // Esc that ends annotating is spent: a host layer around the composer (a panel that closes on Esc) must not also react to it.\n    if (event.key === 'Escape' && !session.getSnapshot().bubble) { event.preventDefault(); event.stopPropagation(); void session.done(); }\n  };\n  view?.addEventListener('keydown', onKey, { capture: true });\n  session.resume(mode ? { mode } : {});\n  const stop = session.subscribe(() => {\n    if (session.getSnapshot().phase === 'active') return;\n    view?.removeEventListener('keydown', onKey, { capture: true });\n    stop();\n  });\n}\n\n/**\n * The composer's `feedback` prop for a session: ONE annotate toggle (targeting with a hover highlight; point mode on touch and compact\n * screens, and again after Esc to add more), a count of the notes taken, and Send attaching them: a saved report as its `@` mention (the host's mention resolver inlines\n * the stored report with the person's access), otherwise the rendered report inline in a fenced block. Pair it with `NoteBubble`.\n */\nexport function useComposerFeedback(session: FeedbackSession | undefined): ComposerFeedbackProp | undefined {\n  const state = useSyncState(session);\n  if (!session || !state) return undefined;\n  const open = state.phase === 'active' || state.phase === 'processing';\n  return {\n    annotate: () => {\n      const phase = session.getSnapshot().phase;\n      if (phase === 'active') void session.done();\n      else if (phase === 'idle' || phase === 'review') startAnnotating(session);\n    },\n    active: open,\n    // A note being typed in the pin counts: Send saves it.\n    count: noteCount(state) + (state.bubble?.fresh && state.bubble.text.trim() ? 1 : 0),\n    clear: () => { session.highlight(undefined); session.discard(); },\n    attach: async text => {\n      // Send while annotating ends it first: the pin being typed is kept.\n      if (session.getSnapshot().phase === 'active') await session.done();\n      const attached = await session.attach();\n      if (attached.kind === 'refused') return attached;\n      const body = attached.kind === 'mention' ? `@${attached.path}` : fenced(attached.text);\n      return { kind: 'ok', text: text.trim() ? `${text.trimEnd()}\\n\\n${body}` : body };\n    },\n    sent: () => session.sent(),\n  };\n}\n\n/** Notes sent one by one in the current round of comment mode (`useSendEachNote`), for the banner; a new round starts at zero. */\nconst sentInRound = new WeakMap<FeedbackSession, number>();\nexport const notesSent = (session: FeedbackSession): number => sentInRound.get(session) ?? 0;\n\n/**\n * Each note goes to the chat the moment it is added: its element and text as one message (`send`, the chat's follow-up send), and\n * comment mode stays on for the next note. Nothing waits in a hidden batch, and the agent's reply follows in the conversation. Without\n * `send`, the notes wait for the person's next message as before. A refused report or a failed send stays in the review, where the composer shows it.\n */\nexport function useSendEachNote(session: FeedbackSession | undefined, send: ((text: string) => Promise<unknown>) | undefined): void {\n  const state = useSyncState(session);\n  const busy = useRef(false);\n  useEffect(() => {\n    if (!session || !send || !state || busy.current) return;\n    if (state.phase !== 'active' || state.bubble || !state.notes.some(note => note.text.trim())) return;\n    busy.current = true;\n    const mode = state.mode === 'point' ? 'point' : undefined;\n    void (async () => {\n      let again = false;\n      try {\n        await session.done();\n        const attached = await session.attach();\n        if (attached.kind === 'refused') return;\n        const submission = await send(attached.kind === 'mention' ? `@${attached.path}` : fenced(attached.text)).catch(() => undefined);\n        if (submission === false || submission === undefined || submission === null) return;\n        sentInRound.set(session, notesSent(session) + noteCount(session.getSnapshot()));\n        session.sent();\n        again = true;\n      } finally {\n        busy.current = false;\n        if (again) startAnnotating(session, mode, false);\n      }\n    })();\n  }, [session, send, state]);\n}\n\nconst NO_STATE = { getSnapshot: () => undefined, subscribe: () => () => {} };\nfunction useSyncState(session: FeedbackSession | undefined): FeedbackSessionSnapshot | undefined {\n  return useExternal<FeedbackSessionSnapshot | undefined>(session ?? NO_STATE);\n}\n\n/** What `usePointComments` returns: the structural shape of the maquette viewer's `MaquetteComments` (any viewer may take it). */\nexport interface PointCommentsProp {\n  /** A host-owned proxy element for an opaque frame pick, checked by the session's root and privacy policy. */\n  readonly pick: (element: Element) => void;\n  readonly reposition: () => void;\n  /** Clicks are currently captured, false during Use app or processing. */\n  readonly picking: boolean;\n  /** The session is annotating now (point mode or feedback mode). */\n  readonly active: boolean;\n  /** Point mode on the page, keeping the notes already taken (from the review too); Done when it is on. Esc ends it like the composer's toggle. */\n  readonly point: () => void;\n  /** Every pin with a marked element: its number and the `data-feedback-id` it sits in (`SessionNote.feedbackId`). */\n  readonly pins: readonly { readonly number: number; readonly target: string }[];\n}\n\n/**\n * Comment pins for a viewer inside the page (the maquette viewer's `comments`): the same session, notes, bubble, review and Send as the\n * composer's toggle, entered in point mode from the viewer's own icon. A viewer marks its parts with `data-feedback-id` and matches the\n * pins on them. Undefined without a session, so the viewer shows no icon.\n */\nexport function usePointComments(session: FeedbackSession | undefined): PointCommentsProp | undefined {\n  const state = useSyncState(session);\n  // One object per session state, so a host that puts it in a memoized kind list re-renders only when the pins or the mode change.\n  return useMemo(() => !session || !state ? undefined : {\n    active: state.phase === 'active' || state.phase === 'processing',\n    pick: session.pick,\n    reposition: session.reposition,\n    picking: state.phase === 'active' && !state.using,\n    point: () => {\n      const phase = session.getSnapshot().phase;\n      if (phase === 'active') void session.done();\n      else if (phase === 'idle' || phase === 'review') startAnnotating(session, 'point');\n    },\n    pins: state.notes.flatMap(note => note.feedbackId ? [{ number: note.number, target: note.feedbackId }] : []),\n  }, [session, state]);\n}\n",
       "type": "registry:component",
       "target": "components/feedback/feedback-session.tsx"
     },

package/r/file-tree.json

@@ -4,15 +4,15 @@
   "title": "File tree",
   "description": "Browse, search, upload and inspect retained versions through one revisionProvider binding. Uses the consumer's shadcn Button and dropdown-menu with shared version-history rows; Base UI style only.",
   "dependencies": [
-    "@hachej/boring-ui-kit@^0.4.11",
-    "@hachej/boring-files@^0.4.11",
+    "@hachej/boring-ui-kit@^0.4.13",
+    "@hachej/boring-files@^0.4.13",
     "react@^19.0.0",
     "lucide-react@^1.51.0"
   ],
   "registryDependencies": [
-    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.11/r/theme.json",
-    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.11/r/utils.json",
-    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.11/r/version-history.json",
+    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.13/r/theme.json",
+    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.13/r/utils.json",
+    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.13/r/version-history.json",
     "button",
     "dropdown-menu",
     "collapsible",

package/r/highlights.json

@@ -4,13 +4,13 @@
   "title": "Anchored highlights",
   "description": "Exact Markdown highlights and comments in a conditional workspace sidecar.",
   "dependencies": [
-    "@hachej/boring-ui-kit@^0.4.11",
-    "@hachej/boring-files@^0.4.11",
+    "@hachej/boring-ui-kit@^0.4.13",
+    "@hachej/boring-files@^0.4.13",
     "react@^19.0.0",
     "react-dom@^19.0.0"
   ],
   "registryDependencies": [
-    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.11/r/markdown-editor.json",
+    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.13/r/markdown-editor.json",
     "button",
     "textarea",
     "label",

package/r/html-viewer.json

@@ -4,13 +4,13 @@
   "title": "HTML source and passive preview",
   "description": "Exact HTML source editing with a reconstructed passive preview and borrowed controller. Browser security qualification remains separate.",
   "dependencies": [
-    "@hachej/boring-ui-kit@^0.4.11",
-    "@hachej/boring-files@^0.4.11",
+    "@hachej/boring-ui-kit@^0.4.13",
+    "@hachej/boring-files@^0.4.13",
     "react@^19.0.0",
     "react-dom@^19.0.0"
   ],
   "registryDependencies": [
-    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.11/r/button.json"
+    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.13/r/button.json"
   ],
   "files": [
     {

package/r/looks-viewer.json

@@ -8,7 +8,7 @@
     "lucide-react@^1.51.0"
   ],
   "registryDependencies": [
-    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.11/r/mockup-viewer.json",
+    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.13/r/mockup-viewer.json",
     "alert",
     "button",
     "card",
@@ -17,15 +17,21 @@
   "files": [
     {
       "path": "registry/looks-viewer/looks-viewer.tsx",
-      "content": "'use client';\n\nimport { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';\nimport type { ComponentType, ReactNode } from 'react';\nimport { CheckIcon, PaletteIcon } from 'lucide-react';\nimport { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert';\nimport { Button } from '@/components/ui/button';\nimport { Card, CardAction, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';\nimport { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group';\nimport { MockupViewer } from '../mockup-viewer/mockup-viewer';\nimport type { ShadcnTheme } from '../mockup-viewer/mockup-viewer';\nimport { besideLooks, parseLooks, swatches } from './looks';\nimport type { Look, Looks } from './looks';\n\nexport { parseLooks, parseShadcnTheme, swatches, besideLooks, shadcnValue, SHADCN_COLOR_VARIABLES, SHADCN_SHAPE_VARIABLES } from './looks';\nexport type { Look, Looks, LayoutVariant } from './looks';\n\nexport const isLooksPath = (path: string): boolean => /\\.looks\\.json$/i.test(path);\n\n/** The person pressed Pick: the host says it in the conversation (or records it); the viewer only marks it. */\nexport interface LookPick {\n  readonly kind: 'look' | 'layout';\n  readonly id: string;\n  readonly label: string;\n  /** The looks file the pick was made in. */\n  readonly path: string;\n}\n\nexport interface LooksViewerProps {\n  readonly text: string;\n  readonly path?: string | undefined;\n  /** Another file of the workspace as text (the artifact panel's `read`): the key screen and the layouts, next to the looks file. */\n  readonly read?: ((path: string) => Promise<string | undefined>) | undefined;\n  readonly onPick?: ((pick: LookPick) => void) | undefined;\n  readonly locale?: 'en' | 'fr' | undefined;\n  readonly onReady?: (() => void) | undefined;\n  readonly onFailed?: ((reason: string) => void) | undefined;\n}\n\nconst LABELS = {\n  en: { looks: 'Pick a look', layouts: 'Pick a layout', layoutsIn: (look: string) => `In the ${look} look`, pick: 'Pick', picked: 'Picked', light: 'Light', dark: 'Dark',\n    loading: 'Loading the looks…', missing: 'The key screen cannot be read.', invalid: 'These looks cannot be shown', font: 'Font', radius: 'Roundness', look: (label: string) => `${label} look`, layout: (label: string) => `${label} layout` },\n  fr: { looks: 'Choisir un style', layouts: 'Choisir une mise en page', layoutsIn: (look: string) => `Dans le style ${look}`, pick: 'Choisir', picked: 'Choisi', light: 'Clair', dark: 'Sombre',\n    loading: 'Chargement des styles…', missing: \"L'écran clé est illisible.\", invalid: 'Ces styles ne peuvent pas être affichés', font: 'Police', radius: 'Arrondi', look: (label: string) => `Style ${label}`, layout: (label: string) => `Mise en page ${label}` },\n} as const;\n\n/** The key screen drawn at a desktop (or, in a narrow column, phone) width and scaled into the card, so a look reads as the whole app. */\nfunction ScaledMockup({ text, theme, mode, title, onReady }: { readonly text: string; readonly theme: ShadcnTheme; readonly mode?: 'light' | 'dark' | undefined; readonly title: string; readonly onReady: () => void }) {\n  const outer = useRef<HTMLDivElement>(null);\n  const [width, setWidth] = useState(0);\n  useLayoutEffect(() => {\n    const element = outer.current;\n    if (!element) return undefined;\n    const measure = () => setWidth(element.getBoundingClientRect().width);\n    measure();\n    if (typeof ResizeObserver === 'undefined') return undefined;\n    const observer = new ResizeObserver(measure);\n    observer.observe(element);\n    return () => observer.disconnect();\n  }, []);\n  // A phone draws the phone layout of the screen; a narrow column on a desktop still draws the desktop one, smaller.\n  const phone = typeof matchMedia === 'function' && matchMedia('(max-width: 639px)').matches;\n  const virtual = phone ? { w: 390, h: 640 } : { w: 1024, h: 600 };\n  const scale = width > 0 ? width / virtual.w : 0.5;\n  return <div ref={outer} data-testid=\"looks-frame\" className=\"relative w-full overflow-hidden bg-muted\" style={{ height: Math.round(virtual.h * scale) }}>\n    <div className=\"absolute top-0 left-0 origin-top-left\" style={{ width: virtual.w, height: virtual.h, transform: `scale(${scale})` }}>\n      <MockupViewer text={text} themeOverride={theme} mode={mode} title={title} onReady={onReady} />\n    </div>\n  </div>;\n}\n\n/** The swatch's corner, in a 15px square: a rem radius at 16px, capped. */\nconst corner = (radius: string) => Math.min(15, Math.max(0, parseFloat(radius) * (radius.endsWith('px') ? 1 : 16)));\n\nfunction Swatches({ look, dark, labels }: { readonly look: Look; readonly dark: boolean; readonly labels: (typeof LABELS)['en' | 'fr'] }) {\n  const swatch = swatches(look, dark);\n  return <div data-testid=\"looks-swatches\" className=\"flex flex-wrap items-center gap-3 text-xs text-muted-foreground\">\n    <svg role=\"img\" aria-label={swatch.colors.map(color => color.name).join(', ')} width={swatch.colors.length * 20} height=\"18\" viewBox={`0 0 ${swatch.colors.length * 20} 18`}>\n      {swatch.colors.map((color, index) => <circle key={color.name} cx={index * 20 + 9} cy=\"9\" r=\"8\" fill={color.value} stroke=\"currentColor\" strokeOpacity=\"0.3\"><title>{`${color.name}: ${color.value}`}</title></circle>)}\n    </svg>\n    <span title={labels.font} style={{ fontFamily: look.theme.theme?.['font-sans'] }}>{swatch.heading === swatch.font ? swatch.font : `${swatch.heading} / ${swatch.font}`}</span>\n    <span className=\"flex items-center gap-1\" title={labels.radius}><svg aria-hidden=\"true\" width=\"18\" height=\"18\" viewBox=\"0 0 18 18\"><path d={`M2 17 V${2 + corner(swatch.radius)} Q2 2 ${2 + corner(swatch.radius)} 2 H17`} fill=\"none\" stroke=\"currentColor\" strokeWidth=\"2\" /></svg>{swatch.radius}</span>\n  </div>;\n}\n\nexport function LooksViewer({ text, path = '', read, onPick, locale = 'en', onReady, onFailed }: LooksViewerProps) {\n  const labels = LABELS[locale];\n  const parsed = useMemo(() => parseLooks(text), [text]);\n  const spec: Looks | undefined = parsed.kind === 'ok' ? parsed.looks : undefined;\n  const sources = useMemo(() => spec ? [...new Set([spec.mockup, ...spec.layouts.map(layout => layout.mockup)])] : [], [spec]);\n  const [files, setFiles] = useState<{ readonly key: string; readonly texts: ReadonlyMap<string, string> } | 'missing'>();\n  const key = JSON.stringify([path, sources]);\n  useEffect(() => {\n    if (!sources.length) return undefined;\n    let live = true;\n    setFiles(undefined);\n    void Promise.all(sources.map(async relative => [relative, read ? await read(besideLooks(path, relative)).catch(() => undefined) : undefined] as const)).then(entries => {\n      if (!live) return;\n      if (entries.some(([, value]) => value === undefined)) { setFiles('missing'); onFailed?.('a mock-up named by the looks file cannot be read'); return; }\n      setFiles({ key, texts: new Map(entries as [string, string][]) });\n    });\n    return () => { live = false; };\n  }, [key, read]); // eslint-disable-line react-hooks/exhaustive-deps\n  const [mode, setMode] = useState<'light' | 'dark' | undefined>();\n  const [look, setLook] = useState<string | undefined>(spec?.look);\n  const [layout, setLayout] = useState<string>();\n  useEffect(() => { setLook(spec?.look); setLayout(undefined); }, [text]); // eslint-disable-line react-hooks/exhaustive-deps\n  const frames = spec ? (spec.looks.length > 1 ? spec.looks.length : 0) + spec.layouts.length : 0;\n  const ready = useRef(new Set<string>());\n  useEffect(() => { ready.current = new Set(); }, [text]);\n  const frameReady = useCallback((id: string) => () => {\n    ready.current.add(id);\n    if (ready.current.size === frames) onReady?.();\n  }, [frames, onReady]);\n  useEffect(() => { if (parsed.kind === 'invalid') onFailed?.(`invalid looks file: ${parsed.issues.slice(0, 3).join('; ')}`); }, [parsed]); // eslint-disable-line react-hooks/exhaustive-deps\n  if (parsed.kind === 'invalid' || !spec) return <Alert role=\"alert\" data-testid=\"looks-invalid\"><AlertTitle>{labels.invalid}</AlertTitle>\n    <AlertDescription>{parsed.kind === 'invalid' ? parsed.issues.slice(0, 6).join('; ') : ''}</AlertDescription></Alert>;\n  if (files === 'missing') return <Alert role=\"alert\"><AlertTitle>{labels.missing}</AlertTitle></Alert>;\n  if (!files || files.key !== key) return <p role=\"status\" className=\"p-3 text-muted-foreground\">{labels.loading}</p>;\n  const keyScreen = files.texts.get(spec.mockup)!;\n  const inLook = spec.looks.find(item => item.id === look) ?? spec.looks.find(item => item.id === spec.look) ?? spec.looks[0]!;\n  const dark = mode === 'dark';\n  const pick = (kind: LookPick['kind'], id: string, label: string) => { if (kind === 'look') setLook(id); else setLayout(id); onPick?.({ kind, id, label, path }); };\n  return <div data-boring=\"looks-viewer\" className=\"flex flex-col gap-6 p-3 md:p-4\">\n    <div className=\"flex items-center justify-between gap-3\">\n      <h2 className=\"text-lg font-semibold\">{spec.looks.length > 1 ? labels.looks : labels.layouts}</h2>\n      <ToggleGroup value={[mode ?? 'host']} onValueChange={(value: unknown[]) => { const next = value[0]; setMode(next === 'light' || next === 'dark' ? next : undefined); }} aria-label={`${labels.light} / ${labels.dark}`}>\n        <ToggleGroupItem value=\"light\" data-testid=\"looks-light\">{labels.light}</ToggleGroupItem>\n        <ToggleGroupItem value=\"dark\" data-testid=\"looks-dark\">{labels.dark}</ToggleGroupItem>\n      </ToggleGroup>\n    </div>\n    {spec.looks.length > 1 && <section aria-label={labels.looks} data-testid=\"looks-grid\" className=\"grid gap-4 md:grid-cols-2\">\n      {spec.looks.map(item => <Choice key={item.id} testId={`look-${item.id}`} title={item.label} line={item.personality} chosen={inLook.id === item.id && look !== undefined} labels={labels}\n        onPick={() => pick('look', item.id, item.label)} extra={<Swatches look={item} dark={dark} labels={labels} />}>\n        <ScaledMockup text={keyScreen} theme={item.theme} mode={mode} title={labels.look(item.label)} onReady={frameReady(`look:${item.id}`)} />\n      </Choice>)}\n    </section>}\n    {spec.layouts.length > 0 && <section aria-label={labels.layouts} data-testid=\"layouts-grid\" className=\"flex flex-col gap-3\">\n      {spec.looks.length > 1 && <h2 className=\"text-lg font-semibold\">{labels.layouts}</h2>}\n      <p className=\"text-sm text-muted-foreground\">{labels.layoutsIn(inLook.label)}</p>\n      <div className={spec.layouts.length > 2 ? 'grid gap-4 md:grid-cols-2 xl:grid-cols-3' : 'grid gap-4 md:grid-cols-2'}>\n        {spec.layouts.map(item => <Choice key={item.id} testId={`layout-${item.id}`} title={item.label} line={item.why} chosen={layout === item.id} labels={labels} onPick={() => pick('layout', item.id, item.label)}>\n          <ScaledMockup text={files.texts.get(item.mockup)!} theme={inLook.theme} mode={mode} title={labels.layout(item.label)} onReady={frameReady(`layout:${item.id}`)} />\n        </Choice>)}\n      </div>\n    </section>}\n  </div>;\n}\n\nfunction Choice({ testId, title, line, chosen, labels, onPick, extra, children }: { readonly testId: string; readonly title: string; readonly line?: string | undefined; readonly chosen: boolean; readonly labels: (typeof LABELS)['en' | 'fr']; readonly onPick: () => void; readonly extra?: ReactNode; readonly children: ReactNode }) {\n  return <Card data-testid={testId} data-chosen={chosen ? '' : undefined}>\n    <CardContent>{children}</CardContent>\n    <CardHeader>\n      <CardTitle>{title}</CardTitle>\n      {line && <CardDescription>{line}</CardDescription>}\n      <CardAction>\n        <Button size=\"sm\" variant={chosen ? 'default' : 'outline'} aria-pressed={chosen} data-testid={`${testId}-pick`} onClick={onPick}>\n          {chosen && <CheckIcon data-icon=\"inline-start\" aria-hidden=\"true\" />}{chosen ? labels.picked : labels.pick}\n        </Button>\n      </CardAction>\n      {extra}\n    </CardHeader>\n  </Card>;\n}\n\nexport interface LooksKind {\n  readonly match: (target: { readonly resource: { readonly path: string } }) => boolean;\n  readonly label: string;\n  readonly icon: ComponentType<{ readonly className?: string; readonly 'aria-hidden'?: boolean | 'true' }>;\n  readonly renderer: (props: { readonly text: string; readonly onReady?: (() => void) | undefined; readonly onFailed?: ((reason: string) => void) | undefined; readonly read?: ((path: string) => Promise<string | undefined>) | undefined; readonly artifact?: { readonly target: { readonly resource: { readonly path: string } } } | undefined }) => ReactNode;\n  readonly waitsForReady: true;\n}\n\n/** The `*.looks.json` kind: opt-in, like the board. `onPick` is the host's (the PM page says the pick in the conversation). */\nexport function createLooksKind({ onPick, locale }: { readonly onPick?: ((pick: LookPick) => void) | undefined; readonly locale?: 'en' | 'fr' | undefined } = {}): LooksKind {\n  return { match: target => isLooksPath(target.resource.path), label: locale === 'fr' ? 'Styles' : 'Looks', icon: PaletteIcon, waitsForReady: true,\n    renderer: ({ text, artifact, read, onReady, onFailed }) => <LooksViewer key={artifact?.target.resource.path} text={text} path={artifact?.target.resource.path} read={read} onPick={onPick} locale={locale} onReady={onReady} onFailed={onFailed} /> };\n}\n",
+      "content": "'use client';\n\nimport { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';\nimport type { ReactNode } from 'react';\nimport { CheckIcon } from 'lucide-react';\nimport { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert';\nimport { Button } from '@/components/ui/button';\nimport { Card, CardAction, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';\nimport { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group';\nimport { MockupViewer } from '../mockup-viewer/mockup-viewer';\nimport type { ShadcnTheme } from '../mockup-viewer/mockup-viewer';\nimport { besideLooks, parseLooks, swatches } from './looks';\nimport type { Look, Looks } from './looks';\n\nexport { isLooksPath, parseLooks, parseShadcnTheme, swatches, besideLooks, shadcnValue, SHADCN_COLOR_VARIABLES, SHADCN_SHAPE_VARIABLES } from './looks';\nexport type { Look, Looks, LayoutVariant } from './looks';\n\n\n/** The person pressed Pick: the host says it in the conversation (or records it); the viewer only marks it. */\nexport interface LookPick {\n  readonly kind: 'look' | 'layout';\n  readonly id: string;\n  readonly label: string;\n  /** The looks file the pick was made in. */\n  readonly path: string;\n}\n\nexport interface LooksViewerProps {\n  readonly text: string;\n  readonly path?: string | undefined;\n  /** Another file of the workspace as text (the artifact panel's `read`): the key screen and the layouts, next to the looks file. */\n  readonly read?: ((path: string) => Promise<string | undefined>) | undefined;\n  readonly onPick?: ((pick: LookPick) => void) | undefined;\n  readonly locale?: 'en' | 'fr' | undefined;\n  readonly onReady?: (() => void) | undefined;\n  readonly onFailed?: ((reason: string) => void) | undefined;\n}\n\nconst LABELS = {\n  en: { looks: 'Pick a look', layouts: 'Pick a layout', layoutsIn: (look: string) => `In the ${look} look`, pick: 'Pick', picked: 'Picked', light: 'Light', dark: 'Dark',\n    loading: 'Loading the looks…', missing: 'The key screen cannot be read.', invalid: 'These looks cannot be shown', font: 'Font', radius: 'Roundness', look: (label: string) => `${label} look`, layout: (label: string) => `${label} layout` },\n  fr: { looks: 'Choisir un style', layouts: 'Choisir une mise en page', layoutsIn: (look: string) => `Dans le style ${look}`, pick: 'Choisir', picked: 'Choisi', light: 'Clair', dark: 'Sombre',\n    loading: 'Chargement des styles…', missing: \"L'écran clé est illisible.\", invalid: 'Ces styles ne peuvent pas être affichés', font: 'Police', radius: 'Arrondi', look: (label: string) => `Style ${label}`, layout: (label: string) => `Mise en page ${label}` },\n} as const;\n\n/** The key screen drawn at a desktop (or, in a narrow column, phone) width and scaled into the card, so a look reads as the whole app. */\nfunction ScaledMockup({ text, theme, mode, title, onReady }: { readonly text: string; readonly theme: ShadcnTheme; readonly mode?: 'light' | 'dark' | undefined; readonly title: string; readonly onReady: () => void }) {\n  const outer = useRef<HTMLDivElement>(null);\n  const [width, setWidth] = useState(0);\n  useLayoutEffect(() => {\n    const element = outer.current;\n    if (!element) return undefined;\n    const measure = () => setWidth(element.getBoundingClientRect().width);\n    measure();\n    if (typeof ResizeObserver === 'undefined') return undefined;\n    const observer = new ResizeObserver(measure);\n    observer.observe(element);\n    return () => observer.disconnect();\n  }, []);\n  // A phone draws the phone layout of the screen; a narrow column on a desktop still draws the desktop one, smaller.\n  const phone = typeof matchMedia === 'function' && matchMedia('(max-width: 639px)').matches;\n  const virtual = phone ? { w: 390, h: 640 } : { w: 1024, h: 600 };\n  const scale = width > 0 ? width / virtual.w : 0.5;\n  return <div ref={outer} data-testid=\"looks-frame\" className=\"relative w-full overflow-hidden bg-muted\" style={{ height: Math.round(virtual.h * scale) }}>\n    <div className=\"absolute top-0 left-0 origin-top-left\" style={{ width: virtual.w, height: virtual.h, transform: `scale(${scale})` }}>\n      <MockupViewer text={text} themeOverride={theme} mode={mode} title={title} onReady={onReady} />\n    </div>\n  </div>;\n}\n\n/** The swatch's corner, in a 15px square: a rem radius at 16px, capped. */\nconst corner = (radius: string) => Math.min(15, Math.max(0, parseFloat(radius) * (radius.endsWith('px') ? 1 : 16)));\n\nfunction Swatches({ look, dark, labels }: { readonly look: Look; readonly dark: boolean; readonly labels: (typeof LABELS)['en' | 'fr'] }) {\n  const swatch = swatches(look, dark);\n  return <div data-testid=\"looks-swatches\" className=\"flex flex-wrap items-center gap-3 text-xs text-muted-foreground\">\n    <svg role=\"img\" aria-label={swatch.colors.map(color => color.name).join(', ')} width={swatch.colors.length * 20} height=\"18\" viewBox={`0 0 ${swatch.colors.length * 20} 18`}>\n      {swatch.colors.map((color, index) => <circle key={color.name} cx={index * 20 + 9} cy=\"9\" r=\"8\" fill={color.value} stroke=\"currentColor\" strokeOpacity=\"0.3\"><title>{`${color.name}: ${color.value}`}</title></circle>)}\n    </svg>\n    <span title={labels.font} style={{ fontFamily: look.theme.theme?.['font-sans'] }}>{swatch.heading === swatch.font ? swatch.font : `${swatch.heading} / ${swatch.font}`}</span>\n    <span className=\"flex items-center gap-1\" title={labels.radius}><svg aria-hidden=\"true\" width=\"18\" height=\"18\" viewBox=\"0 0 18 18\"><path d={`M2 17 V${2 + corner(swatch.radius)} Q2 2 ${2 + corner(swatch.radius)} 2 H17`} fill=\"none\" stroke=\"currentColor\" strokeWidth=\"2\" /></svg>{swatch.radius}</span>\n  </div>;\n}\n\nexport function LooksViewer({ text, path = '', read, onPick, locale = 'en', onReady, onFailed }: LooksViewerProps) {\n  const labels = LABELS[locale];\n  const parsed = useMemo(() => parseLooks(text), [text]);\n  const spec: Looks | undefined = parsed.kind === 'ok' ? parsed.looks : undefined;\n  const sources = useMemo(() => spec ? [...new Set([spec.mockup, ...spec.layouts.map(layout => layout.mockup)])] : [], [spec]);\n  const [files, setFiles] = useState<{ readonly key: string; readonly texts: ReadonlyMap<string, string> } | 'missing'>();\n  const key = JSON.stringify([path, sources]);\n  useEffect(() => {\n    if (!sources.length) return undefined;\n    let live = true;\n    setFiles(undefined);\n    void Promise.all(sources.map(async relative => [relative, read ? await read(besideLooks(path, relative)).catch(() => undefined) : undefined] as const)).then(entries => {\n      if (!live) return;\n      if (entries.some(([, value]) => value === undefined)) { setFiles('missing'); onFailed?.('a mock-up named by the looks file cannot be read'); return; }\n      setFiles({ key, texts: new Map(entries as [string, string][]) });\n    });\n    return () => { live = false; };\n  }, [key, read]); // eslint-disable-line react-hooks/exhaustive-deps\n  const [mode, setMode] = useState<'light' | 'dark' | undefined>();\n  const [look, setLook] = useState<string | undefined>(spec?.look);\n  const [layout, setLayout] = useState<string>();\n  useEffect(() => { setLook(spec?.look); setLayout(undefined); }, [text]); // eslint-disable-line react-hooks/exhaustive-deps\n  const frames = spec ? (spec.looks.length > 1 ? spec.looks.length : 0) + spec.layouts.length : 0;\n  const ready = useRef(new Set<string>());\n  useEffect(() => { ready.current = new Set(); }, [text]);\n  const frameReady = useCallback((id: string) => () => {\n    ready.current.add(id);\n    if (ready.current.size === frames) onReady?.();\n  }, [frames, onReady]);\n  useEffect(() => { if (parsed.kind === 'invalid') onFailed?.(`invalid looks file: ${parsed.issues.slice(0, 3).join('; ')}`); }, [parsed]); // eslint-disable-line react-hooks/exhaustive-deps\n  if (parsed.kind === 'invalid' || !spec) return <Alert role=\"alert\" data-testid=\"looks-invalid\"><AlertTitle>{labels.invalid}</AlertTitle>\n    <AlertDescription>{parsed.kind === 'invalid' ? parsed.issues.slice(0, 6).join('; ') : ''}</AlertDescription></Alert>;\n  if (files === 'missing') return <Alert role=\"alert\"><AlertTitle>{labels.missing}</AlertTitle></Alert>;\n  if (!files || files.key !== key) return <p role=\"status\" className=\"p-3 text-muted-foreground\">{labels.loading}</p>;\n  const keyScreen = files.texts.get(spec.mockup)!;\n  const inLook = spec.looks.find(item => item.id === look) ?? spec.looks.find(item => item.id === spec.look) ?? spec.looks[0]!;\n  const dark = mode === 'dark';\n  const pick = (kind: LookPick['kind'], id: string, label: string) => { if (kind === 'look') setLook(id); else setLayout(id); onPick?.({ kind, id, label, path }); };\n  return <div data-boring=\"looks-viewer\" className=\"flex flex-col gap-6 p-3 md:p-4\">\n    <div className=\"flex items-center justify-between gap-3\">\n      <h2 className=\"text-lg font-semibold\">{spec.looks.length > 1 ? labels.looks : labels.layouts}</h2>\n      <ToggleGroup value={[mode ?? 'host']} onValueChange={(value: unknown[]) => { const next = value[0]; setMode(next === 'light' || next === 'dark' ? next : undefined); }} aria-label={`${labels.light} / ${labels.dark}`}>\n        <ToggleGroupItem value=\"light\" data-testid=\"looks-light\">{labels.light}</ToggleGroupItem>\n        <ToggleGroupItem value=\"dark\" data-testid=\"looks-dark\">{labels.dark}</ToggleGroupItem>\n      </ToggleGroup>\n    </div>\n    {spec.looks.length > 1 && <section aria-label={labels.looks} data-testid=\"looks-grid\" className=\"grid gap-4 md:grid-cols-2\">\n      {spec.looks.map(item => <Choice key={item.id} testId={`look-${item.id}`} title={item.label} line={item.personality} chosen={inLook.id === item.id && look !== undefined} labels={labels}\n        onPick={() => pick('look', item.id, item.label)} extra={<Swatches look={item} dark={dark} labels={labels} />}>\n        <ScaledMockup text={keyScreen} theme={item.theme} mode={mode} title={labels.look(item.label)} onReady={frameReady(`look:${item.id}`)} />\n      </Choice>)}\n    </section>}\n    {spec.layouts.length > 0 && <section aria-label={labels.layouts} data-testid=\"layouts-grid\" className=\"flex flex-col gap-3\">\n      {spec.looks.length > 1 && <h2 className=\"text-lg font-semibold\">{labels.layouts}</h2>}\n      <p className=\"text-sm text-muted-foreground\">{labels.layoutsIn(inLook.label)}</p>\n      <div className={spec.layouts.length > 2 ? 'grid gap-4 md:grid-cols-2 xl:grid-cols-3' : 'grid gap-4 md:grid-cols-2'}>\n        {spec.layouts.map(item => <Choice key={item.id} testId={`layout-${item.id}`} title={item.label} line={item.why} chosen={layout === item.id} labels={labels} onPick={() => pick('layout', item.id, item.label)}>\n          <ScaledMockup text={files.texts.get(item.mockup)!} theme={inLook.theme} mode={mode} title={labels.layout(item.label)} onReady={frameReady(`layout:${item.id}`)} />\n        </Choice>)}\n      </div>\n    </section>}\n  </div>;\n}\n\nfunction Choice({ testId, title, line, chosen, labels, onPick, extra, children }: { readonly testId: string; readonly title: string; readonly line?: string | undefined; readonly chosen: boolean; readonly labels: (typeof LABELS)['en' | 'fr']; readonly onPick: () => void; readonly extra?: ReactNode; readonly children: ReactNode }) {\n  return <Card data-testid={testId} data-chosen={chosen ? '' : undefined}>\n    <CardContent>{children}</CardContent>\n    <CardHeader>\n      <CardTitle>{title}</CardTitle>\n      {line && <CardDescription>{line}</CardDescription>}\n      <CardAction>\n        <Button size=\"sm\" variant={chosen ? 'default' : 'outline'} aria-pressed={chosen} data-testid={`${testId}-pick`} onClick={onPick}>\n          {chosen && <CheckIcon data-icon=\"inline-start\" aria-hidden=\"true\" />}{chosen ? labels.picked : labels.pick}\n        </Button>\n      </CardAction>\n      {extra}\n    </CardHeader>\n  </Card>;\n}\n",
       "type": "registry:component",
       "target": "components/looks-viewer/looks-viewer.tsx"
     },
     {
       "path": "registry/looks-viewer/looks.ts",
-      "content": "// looks@1: the looks an assistant offers for an app (`*.looks.json`). A look is a shadcn theme, exactly as shadcn writes it: a preset\n// code (`npx shadcn apply <code> --only theme,font`) and/or the theme block that preset produces (:root, .dark and the font and radius\n// variables of `@theme inline`). Nothing here invents a theme model: the block's variables are shadcn's own.\nimport type { ShadcnTheme } from '../mockup-viewer/mockup-viewer';\n\n/** The colour variables of a shadcn theme (`:root` and `.dark`). */\nexport const SHADCN_COLOR_VARIABLES: readonly string[] = Object.freeze([\n  'background', 'foreground', 'card', 'card-foreground', 'popover', 'popover-foreground', 'primary', 'primary-foreground',\n  'secondary', 'secondary-foreground', 'muted', 'muted-foreground', 'accent', 'accent-foreground', 'destructive', 'destructive-foreground',\n  // the hairline variable's name is joined: the design scan reads that bare word as a class\n  ['bord', 'er'].join(''), 'input', 'ring', 'chart-1', 'chart-2', 'chart-3', 'chart-4', 'chart-5', 'sidebar', 'sidebar-foreground', 'sidebar-primary',\n  'sidebar-primary-foreground', 'sidebar-accent', 'sidebar-accent-foreground', 'sidebar-border', 'sidebar-ring',\n]);\n/** The non-colour variables a shadcn theme sets: the radius (`:root`) and the font families (`@theme inline`). */\nexport const SHADCN_SHAPE_VARIABLES: readonly string[] = Object.freeze(['radius', 'font-sans', 'font-serif', 'font-mono', 'font-heading']);\n\nconst COLOR = /^(?:#[0-9a-f]{3,8}|(?:oklch|oklab|lab|lch|hsla?|rgba?)\\([0-9a-z .,%/+-]{1,80}\\))$/i;\nconst LENGTH = /^(?:0|\\d{1,2}(?:\\.\\d{1,4})?(?:rem|px|em))$/;\nconst FONT = /^(?:[A-Za-z0-9 ,'\"-]{1,160}|var\\(--font-(?:sans|serif|mono)\\))$/;\nconst ID = /^[a-z0-9][a-z0-9-]{0,39}$/;\n/** A shadcn preset: a code (`bIkeymG`), a named style (`nova`) or a ui.shadcn.com init URL. */\nconst PRESET = /^(?:[A-Za-z0-9]{1,24}|https:\\/\\/ui\\.shadcn\\.com\\/init\\?[A-Za-z0-9=&_.-]{1,600})$/;\n\nexport type ThemeIssue = string;\n\n/** Is this a valid value for that shadcn variable? */\nexport function shadcnValue(name: string, value: string): boolean {\n  if (SHADCN_COLOR_VARIABLES.includes(name)) return COLOR.test(value);\n  if (name === 'radius') return LENGTH.test(value);\n  if (name.startsWith('font-')) return SHADCN_SHAPE_VARIABLES.includes(name) && FONT.test(value);\n  return false;\n}\n\n/**\n * A shadcn theme block (`:root { … } .dark { … } @theme inline { … }`, as `shadcn apply` writes it) into shadcn's `cssVars` shape.\n * Only shadcn theme variables with valid values are accepted; anything else is an issue, never silently kept.\n */\nexport function parseShadcnTheme(css: string): { readonly kind: 'ok'; readonly theme: ShadcnTheme } | { readonly kind: 'invalid'; readonly issues: readonly ThemeIssue[] } {\n  const issues: ThemeIssue[] = [];\n  const out = { theme: {} as Record<string, string>, light: {} as Record<string, string>, dark: {} as Record<string, string> };\n  const text = css.replace(/\\/\\*[\\s\\S]*?\\*\\//g, '');\n  const block = /([^{}]+)\\{([^{}]*)\\}/g;\n  let consumed = '';\n  for (const match of text.matchAll(block)) {\n    consumed += match[0];\n    const selector = match[1]!.trim();\n    const target = selector === ':root' ? out.light : selector === '.dark' ? out.dark : /^@theme(?:\\s+inline)?$/.test(selector) ? out.theme : undefined;\n    if (!target) { issues.push(`unexpected block ${selector.slice(0, 40)}: only :root, .dark and @theme inline`); continue; }\n    for (const raw of match[2]!.split(';')) {\n      const declaration = raw.trim();\n      if (!declaration) continue;\n      const colon = declaration.indexOf(':');\n      const name = declaration.slice(0, colon).trim().replace(/^--/, ''), value = declaration.slice(colon + 1).trim();\n      if (colon < 0 || !declaration.startsWith('--')) { issues.push(`not a variable: ${declaration.slice(0, 40)}`); continue; }\n      // @theme inline also carries shadcn's colour and radius bindings (--color-primary: var(--primary)); they are the wiring, not the look.\n      if (target === out.theme && (/^color-/.test(name) || /^radius-/.test(name))) continue;\n      const allowed = target === out.theme ? name.startsWith('font-') : true;\n      if (!allowed || !shadcnValue(name, value)) { issues.push(`${selector} --${name}: not a shadcn theme variable or not a valid value`); continue; }\n      target[name] = value;\n    }\n  }\n  if (text.replace(block, '').trim()) issues.push('text outside the :root, .dark and @theme blocks');\n  if (!consumed) issues.push('no :root block');\n  for (const name of ['background', 'foreground', 'primary', 'primary-foreground']) {\n    if (!out.light[name]) issues.push(`:root misses --${name}`);\n    if (!out.dark[name]) issues.push(`.dark misses --${name}`);\n  }\n  return issues.length ? { kind: 'invalid', issues } : { kind: 'ok', theme: out };\n}\n\nexport interface Look {\n  readonly id: string;\n  readonly label: string;\n  /** One line: how the app feels in this look. */\n  readonly personality: string;\n  /** The shadcn preset this look applies (`npx shadcn apply <preset> --only theme,font`). */\n  readonly preset?: string | undefined;\n  /** The shadcn theme block, parsed. */\n  readonly theme: ShadcnTheme;\n}\nexport interface LayoutVariant { readonly id: string; readonly label: string; readonly why?: string | undefined; readonly mockup: string }\nexport interface Looks {\n  /** The key screen, a `*.mockup.html` next to the looks file. */\n  readonly mockup: string;\n  readonly looks: readonly Look[];\n  readonly layouts: readonly LayoutVariant[];\n  /** The look the layouts are drawn in (a look's id); absent: the first look. */\n  readonly look?: string | undefined;\n}\n\nconst MOCKUP = /^[A-Za-z0-9][A-Za-z0-9 ._/-]{0,160}\\.mockup\\.html$/i;\nconst text = (value: unknown, max: number) => typeof value === 'string' && value.trim() && value.length <= max ? value.trim() : undefined;\n\n/** Read a `*.looks.json`. Paths are relative to the looks file; a layout is a path or `{ id, label, why?, mockup }`. */\nexport function parseLooks(source: string): { readonly kind: 'ok'; readonly looks: Looks } | { readonly kind: 'invalid'; readonly issues: readonly string[] } {\n  let data: unknown;\n  try { data = JSON.parse(source); } catch { return { kind: 'invalid', issues: ['not JSON'] }; }\n  if (!data || typeof data !== 'object' || Array.isArray(data)) return { kind: 'invalid', issues: ['a looks file is an object { mockup, looks, layouts? }'] };\n  const spec = data as Record<string, unknown>;\n  const issues: string[] = [];\n  const mockup = typeof spec.mockup === 'string' && MOCKUP.test(spec.mockup) && !spec.mockup.includes('..') ? spec.mockup : undefined;\n  if (!mockup) issues.push('mockup: a *.mockup.html path next to the looks file');\n  const rawLooks = Array.isArray(spec.looks) ? spec.looks : [];\n  const rawLayouts = spec.layouts === undefined ? [] : Array.isArray(spec.layouts) ? spec.layouts : null;\n  if (rawLayouts === null) issues.push('layouts: a list');\n  if (rawLooks.length < 1 || rawLooks.length > 6 || (rawLooks.length < 2 && !rawLayouts?.length)) issues.push('looks: 2 to 6 looks (1 when the file compares layouts)');\n  const looks: Look[] = [];\n  rawLooks.forEach((raw, index) => {\n    const item = (raw && typeof raw === 'object' ? raw : {}) as Record<string, unknown>;\n    const at = `looks[${index}]`;\n    const id = typeof item.id === 'string' && ID.test(item.id) ? item.id : undefined;\n    const label = text(item.label, 40), personality = text(item.personality, 160);\n    const preset = item.preset === undefined ? undefined : typeof item.preset === 'string' && PRESET.test(item.preset) ? item.preset : null;\n    if (!id) issues.push(`${at}.id: lowercase letters, digits and dashes`);\n    if (!label) issues.push(`${at}.label: a short name`);\n    if (!personality) issues.push(`${at}.personality: one line`);\n    if (preset === null) issues.push(`${at}.preset: a shadcn preset code or ui.shadcn.com init URL`);\n    const parsed = typeof item.css === 'string' ? parseShadcnTheme(item.css) : undefined;\n    if (!parsed) issues.push(`${at}.css: the shadcn theme block of the look`);\n    else if (parsed.kind === 'invalid') issues.push(...parsed.issues.slice(0, 4).map(issue => `${at}.css: ${issue}`));\n    if (id && label && personality && preset !== null && parsed?.kind === 'ok') looks.push({ id, label, personality, ...(preset ? { preset } : {}), theme: parsed.theme });\n  });\n  if (new Set(looks.map(look => look.id)).size !== looks.length) issues.push('looks: ids are unique');\n  const layouts: LayoutVariant[] = [];\n  (rawLayouts ?? []).forEach((raw, index) => {\n    const item = typeof raw === 'string' ? { mockup: raw } : (raw && typeof raw === 'object' ? raw : {}) as Record<string, unknown>;\n    const path = typeof item.mockup === 'string' && MOCKUP.test(item.mockup) && !item.mockup.includes('..') ? item.mockup : undefined;\n    if (!path) { issues.push(`layouts[${index}]: a *.mockup.html path, or { id, label, why?, mockup }`); return; }\n    const id = typeof item.id === 'string' && ID.test(item.id) ? item.id : String.fromCharCode(97 + index);\n    layouts.push({ id, label: text(item.label, 60) ?? `Layout ${String.fromCharCode(65 + index)}`, ...(text(item.why, 160) ? { why: text(item.why, 160) } : {}), mockup: path });\n  });\n  if (layouts.length > 4) issues.push('layouts: at most 4');\n  const look = spec.look === undefined ? undefined : typeof spec.look === 'string' && looks.some(item => item.id === spec.look) ? spec.look : null;\n  if (look === null) issues.push('look: the id of one of the looks');\n  return issues.length || !mockup ? { kind: 'invalid', issues } : { kind: 'ok', looks: { mockup, looks, layouts, ...(look ? { look } : {}) } };\n}\n\n/** What the swatch row shows: four colours, the font family's first name and the radius. */\nexport function swatches(look: Look, dark = false): { readonly colors: readonly { readonly name: string; readonly value: string }[]; readonly font: string; readonly heading: string; readonly radius: string } {\n  const vars = { ...look.theme.light, ...(dark ? look.theme.dark : undefined) };\n  const family = (value: string | undefined) => (value ?? '').split(',')[0]!.replace(/['\"]/g, '').replace(/ Variable$/, '').trim();\n  const font = family(look.theme.theme?.['font-sans']) || 'System';\n  const headingVar = look.theme.theme?.['font-heading'];\n  return {\n    colors: ['background', 'primary', 'accent', 'foreground'].filter(name => vars[name]).map(name => ({ name, value: vars[name]! })),\n    font, heading: headingVar && !headingVar.includes('var(') ? family(headingVar) : font, radius: vars.radius ?? '0.625rem',\n  };\n}\n\n/** A path named in the looks file, read next to it. */\nexport const besideLooks = (looksPath: string, relative: string): string => looksPath.slice(0, looksPath.lastIndexOf('/') + 1) + relative;\n",
+      "content": "// looks@1: the looks an assistant offers for an app (`*.looks.json`). A look is a shadcn theme, exactly as shadcn writes it: a preset\n// code (`npx shadcn apply <code> --only theme,font`) and/or the theme block that preset produces (:root, .dark and the font and radius\n// variables of `@theme inline`). Nothing here invents a theme model: the block's variables are shadcn's own.\nimport type { ShadcnTheme } from '../mockup-viewer/mockup-viewer';\n\n/** The colour variables of a shadcn theme (`:root` and `.dark`). */\nexport const SHADCN_COLOR_VARIABLES: readonly string[] = Object.freeze([\n  'background', 'foreground', 'card', 'card-foreground', 'popover', 'popover-foreground', 'primary', 'primary-foreground',\n  'secondary', 'secondary-foreground', 'muted', 'muted-foreground', 'accent', 'accent-foreground', 'destructive', 'destructive-foreground',\n  // the hairline variable's name is joined: the design scan reads that bare word as a class\n  ['bord', 'er'].join(''), 'input', 'ring', 'chart-1', 'chart-2', 'chart-3', 'chart-4', 'chart-5', 'sidebar', 'sidebar-foreground', 'sidebar-primary',\n  'sidebar-primary-foreground', 'sidebar-accent', 'sidebar-accent-foreground', 'sidebar-border', 'sidebar-ring',\n]);\n/** The non-colour variables a shadcn theme sets: the radius (`:root`) and the font families (`@theme inline`). */\nexport const SHADCN_SHAPE_VARIABLES: readonly string[] = Object.freeze(['radius', 'font-sans', 'font-serif', 'font-mono', 'font-heading']);\n\nconst COLOR = /^(?:#[0-9a-f]{3,8}|(?:oklch|oklab|lab|lch|hsla?|rgba?)\\([0-9a-z .,%/+-]{1,80}\\))$/i;\nconst LENGTH = /^(?:0|\\d{1,2}(?:\\.\\d{1,4})?(?:rem|px|em))$/;\nconst FONT = /^(?:[A-Za-z0-9 ,'\"-]{1,160}|var\\(--font-(?:sans|serif|mono)\\))$/;\nconst ID = /^[a-z0-9][a-z0-9-]{0,39}$/;\n/** A shadcn preset: a code (`bIkeymG`), a named style (`nova`) or a ui.shadcn.com init URL. */\nconst PRESET = /^(?:[A-Za-z0-9]{1,24}|https:\\/\\/ui\\.shadcn\\.com\\/init\\?[A-Za-z0-9=&_.-]{1,600})$/;\n\nexport type ThemeIssue = string;\n\n/** Is this a valid value for that shadcn variable? */\nexport function shadcnValue(name: string, value: string): boolean {\n  if (SHADCN_COLOR_VARIABLES.includes(name)) return COLOR.test(value);\n  if (name === 'radius') return LENGTH.test(value);\n  if (name.startsWith('font-')) return SHADCN_SHAPE_VARIABLES.includes(name) && FONT.test(value);\n  return false;\n}\n\n/**\n * A shadcn theme block (`:root { … } .dark { … } @theme inline { … }`, as `shadcn apply` writes it) into shadcn's `cssVars` shape.\n * Only shadcn theme variables with valid values are accepted; anything else is an issue, never silently kept.\n */\nexport function parseShadcnTheme(css: string): { readonly kind: 'ok'; readonly theme: ShadcnTheme } | { readonly kind: 'invalid'; readonly issues: readonly ThemeIssue[] } {\n  const issues: ThemeIssue[] = [];\n  const out = { theme: {} as Record<string, string>, light: {} as Record<string, string>, dark: {} as Record<string, string> };\n  const text = css.replace(/\\/\\*[\\s\\S]*?\\*\\//g, '');\n  const block = /([^{}]+)\\{([^{}]*)\\}/g;\n  let consumed = '';\n  for (const match of text.matchAll(block)) {\n    consumed += match[0];\n    const selector = match[1]!.trim();\n    const target = selector === ':root' ? out.light : selector === '.dark' ? out.dark : /^@theme(?:\\s+inline)?$/.test(selector) ? out.theme : undefined;\n    if (!target) { issues.push(`unexpected block ${selector.slice(0, 40)}: only :root, .dark and @theme inline`); continue; }\n    for (const raw of match[2]!.split(';')) {\n      const declaration = raw.trim();\n      if (!declaration) continue;\n      const colon = declaration.indexOf(':');\n      const name = declaration.slice(0, colon).trim().replace(/^--/, ''), value = declaration.slice(colon + 1).trim();\n      if (colon < 0 || !declaration.startsWith('--')) { issues.push(`not a variable: ${declaration.slice(0, 40)}`); continue; }\n      // @theme inline also carries shadcn's colour and radius bindings (--color-primary: var(--primary)); they are the wiring, not the look.\n      if (target === out.theme && (/^color-/.test(name) || /^radius-/.test(name))) continue;\n      const allowed = target === out.theme ? name.startsWith('font-') : true;\n      if (!allowed || !shadcnValue(name, value)) { issues.push(`${selector} --${name}: not a shadcn theme variable or not a valid value`); continue; }\n      target[name] = value;\n    }\n  }\n  if (text.replace(block, '').trim()) issues.push('text outside the :root, .dark and @theme blocks');\n  if (!consumed) issues.push('no :root block');\n  for (const name of ['background', 'foreground', 'primary', 'primary-foreground']) {\n    if (!out.light[name]) issues.push(`:root misses --${name}`);\n    if (!out.dark[name]) issues.push(`.dark misses --${name}`);\n  }\n  return issues.length ? { kind: 'invalid', issues } : { kind: 'ok', theme: out };\n}\n\nexport interface Look {\n  readonly id: string;\n  readonly label: string;\n  /** One line: how the app feels in this look. */\n  readonly personality: string;\n  /** The shadcn preset this look applies (`npx shadcn apply <preset> --only theme,font`). */\n  readonly preset?: string | undefined;\n  /** The shadcn theme block, parsed. */\n  readonly theme: ShadcnTheme;\n}\nexport interface LayoutVariant { readonly id: string; readonly label: string; readonly why?: string | undefined; readonly mockup: string }\nexport interface Looks {\n  /** The key screen, a `*.mockup.html` next to the looks file. */\n  readonly mockup: string;\n  readonly looks: readonly Look[];\n  readonly layouts: readonly LayoutVariant[];\n  /** The look the layouts are drawn in (a look's id); absent: the first look. */\n  readonly look?: string | undefined;\n}\n\nconst MOCKUP = /^[A-Za-z0-9][A-Za-z0-9 ._/-]{0,160}\\.mockup\\.html$/i;\nconst text = (value: unknown, max: number) => typeof value === 'string' && value.trim() && value.length <= max ? value.trim() : undefined;\n\n/** Read a `*.looks.json`. Paths are relative to the looks file; a layout is a path or `{ id, label, why?, mockup }`. */\nexport function parseLooks(source: string): { readonly kind: 'ok'; readonly looks: Looks } | { readonly kind: 'invalid'; readonly issues: readonly string[] } {\n  let data: unknown;\n  try { data = JSON.parse(source); } catch { return { kind: 'invalid', issues: ['not JSON'] }; }\n  if (!data || typeof data !== 'object' || Array.isArray(data)) return { kind: 'invalid', issues: ['a looks file is an object { mockup, looks, layouts? }'] };\n  const spec = data as Record<string, unknown>;\n  const issues: string[] = [];\n  const mockup = typeof spec.mockup === 'string' && MOCKUP.test(spec.mockup) && !spec.mockup.includes('..') ? spec.mockup : undefined;\n  if (!mockup) issues.push('mockup: a *.mockup.html path next to the looks file');\n  const rawLooks = Array.isArray(spec.looks) ? spec.looks : [];\n  const rawLayouts = spec.layouts === undefined ? [] : Array.isArray(spec.layouts) ? spec.layouts : null;\n  if (rawLayouts === null) issues.push('layouts: a list');\n  if (rawLooks.length < 1 || rawLooks.length > 6 || (rawLooks.length < 2 && !rawLayouts?.length)) issues.push('looks: 2 to 6 looks (1 when the file compares layouts)');\n  const looks: Look[] = [];\n  rawLooks.forEach((raw, index) => {\n    const item = (raw && typeof raw === 'object' ? raw : {}) as Record<string, unknown>;\n    const at = `looks[${index}]`;\n    const id = typeof item.id === 'string' && ID.test(item.id) ? item.id : undefined;\n    const label = text(item.label, 40), personality = text(item.personality, 160);\n    const preset = item.preset === undefined ? undefined : typeof item.preset === 'string' && PRESET.test(item.preset) ? item.preset : null;\n    if (!id) issues.push(`${at}.id: lowercase letters, digits and dashes`);\n    if (!label) issues.push(`${at}.label: a short name`);\n    if (!personality) issues.push(`${at}.personality: one line`);\n    if (preset === null) issues.push(`${at}.preset: a shadcn preset code or ui.shadcn.com init URL`);\n    const parsed = typeof item.css === 'string' ? parseShadcnTheme(item.css) : undefined;\n    if (!parsed) issues.push(`${at}.css: the shadcn theme block of the look`);\n    else if (parsed.kind === 'invalid') issues.push(...parsed.issues.slice(0, 4).map(issue => `${at}.css: ${issue}`));\n    if (id && label && personality && preset !== null && parsed?.kind === 'ok') looks.push({ id, label, personality, ...(preset ? { preset } : {}), theme: parsed.theme });\n  });\n  if (new Set(looks.map(look => look.id)).size !== looks.length) issues.push('looks: ids are unique');\n  const layouts: LayoutVariant[] = [];\n  (rawLayouts ?? []).forEach((raw, index) => {\n    const item = typeof raw === 'string' ? { mockup: raw } : (raw && typeof raw === 'object' ? raw : {}) as Record<string, unknown>;\n    const path = typeof item.mockup === 'string' && MOCKUP.test(item.mockup) && !item.mockup.includes('..') ? item.mockup : undefined;\n    if (!path) { issues.push(`layouts[${index}]: a *.mockup.html path, or { id, label, why?, mockup }`); return; }\n    const id = typeof item.id === 'string' && ID.test(item.id) ? item.id : String.fromCharCode(97 + index);\n    layouts.push({ id, label: text(item.label, 60) ?? `Layout ${String.fromCharCode(65 + index)}`, ...(text(item.why, 160) ? { why: text(item.why, 160) } : {}), mockup: path });\n  });\n  if (layouts.length > 4) issues.push('layouts: at most 4');\n  const look = spec.look === undefined ? undefined : typeof spec.look === 'string' && looks.some(item => item.id === spec.look) ? spec.look : null;\n  if (look === null) issues.push('look: the id of one of the looks');\n  return issues.length || !mockup ? { kind: 'invalid', issues } : { kind: 'ok', looks: { mockup, looks, layouts, ...(look ? { look } : {}) } };\n}\n\n/** What the swatch row shows: four colours, the font family's first name and the radius. */\nexport function swatches(look: Look, dark = false): { readonly colors: readonly { readonly name: string; readonly value: string }[]; readonly font: string; readonly heading: string; readonly radius: string } {\n  const vars = { ...look.theme.light, ...(dark ? look.theme.dark : undefined) };\n  const family = (value: string | undefined) => (value ?? '').split(',')[0]!.replace(/['\"]/g, '').replace(/ Variable$/, '').trim();\n  const font = family(look.theme.theme?.['font-sans']) || 'System';\n  const headingVar = look.theme.theme?.['font-heading'];\n  return {\n    colors: ['background', 'primary', 'accent', 'foreground'].filter(name => vars[name]).map(name => ({ name, value: vars[name]! })),\n    font, heading: headingVar && !headingVar.includes('var(') ? family(headingVar) : font, radius: vars.radius ?? '0.625rem',\n  };\n}\n\n/** A path named in the looks file, read next to it. */\nexport const besideLooks = (looksPath: string, relative: string): string => looksPath.slice(0, looksPath.lastIndexOf('/') + 1) + relative;\n\n/** A `*.looks.json` file: the looks kind's match, here so the kind does not load the viewer. */\nexport const isLooksPath = (path: string): boolean => /\\.looks\\.json$/i.test(path);\n",
       "type": "registry:lib",
       "target": "components/looks-viewer/looks.ts"
+    },
+    {
+      "path": "registry/looks-viewer/looks-kind.tsx",
+      "content": "'use client';\n\nimport { lazy } from 'react';\nimport type { ComponentType, ReactNode } from 'react';\nimport { PaletteIcon } from 'lucide-react';\nimport { isLooksPath } from './looks';\nimport type { LookPick } from './looks-viewer';\n\nconst LooksViewer = lazy(() => import('./looks-viewer').then(module => ({ default: module.LooksViewer })));\n\nexport interface LooksKind {\n  readonly match: (target: { readonly resource: { readonly path: string } }) => boolean;\n  readonly label: string;\n  readonly icon: ComponentType<{ readonly className?: string; readonly 'aria-hidden'?: boolean | 'true' }>;\n  readonly renderer: (props: { readonly text: string; readonly onReady?: (() => void) | undefined; readonly onFailed?: ((reason: string) => void) | undefined; readonly read?: ((path: string) => Promise<string | undefined>) | undefined; readonly artifact?: { readonly target: { readonly resource: { readonly path: string } } } | undefined }) => ReactNode;\n  readonly waitsForReady: true;\n}\n\n/** The `*.looks.json` kind: opt-in, like the board. `onPick` is the host's (the PM page says the pick in the conversation). The viewer loads on first open. */\nexport function createLooksKind({ onPick, locale }: { readonly onPick?: ((pick: LookPick) => void) | undefined; readonly locale?: 'en' | 'fr' | undefined } = {}): LooksKind {\n  return { match: target => isLooksPath(target.resource.path), label: locale === 'fr' ? 'Styles' : 'Looks', icon: PaletteIcon, waitsForReady: true,\n    renderer: ({ text, artifact, read, onReady, onFailed }) => <LooksViewer key={artifact?.target.resource.path} text={text} path={artifact?.target.resource.path} read={read} onPick={onPick} locale={locale} onReady={onReady} onFailed={onFailed} /> };\n}\n",
+      "type": "registry:component",
+      "target": "components/looks-viewer/looks-kind.tsx"
     }
   ],
   "type": "registry:block"