@openrails/contentkit-ui 0.0.0-stage → 0.68.1

package/README.md

@@ -1,3 +1,471 @@
-# Temporary Holding Version
+# @openrails/contentkit-ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+ContentKit in the browser: a framework-free client, content URLs, React hooks
+and styled components (uploads with cropping, video posters, galleries, HLS
+playback, comments, reactions, favorites, polls and their staff screens).
+`@openrails/contentkit-ui@X.Y.Z` speaks ContentKit `vX.Y.Z`.
+
+```sh
+pnpm add @openrails/contentkit-ui@X.Y.Z
+```
+
+| Import | Contents | Needs |
+| --- | --- | --- |
+| `@openrails/contentkit-ui` | styled components, `ContentKitUiProvider`, i18n | `react`, `react-dom` |
+| `@openrails/contentkit-ui/react` | `ContentKitProvider` and every hook | `react` |
+| `@openrails/contentkit-ui/client` | `createContentKitClient`, `ContentKitError`, generated wire types, crop/aspect/rendition/ABR/gallery math | nothing |
+| `@openrails/contentkit-ui/urls` | content codes, `[/{lang}]/{route}/{CODE}[/{slug}]` paths, `canonical` | nothing |
+| `@openrails/contentkit-ui/locales/{de,es,ja,ko,zh}` | message bundles (English is built in) | |
+| `@openrails/contentkit-ui/styles.css` | the stylesheet, scoped under `.ckui` (the root entry also installs it) | |
+
+`react` and `react-dom` are optional peers, so `/client` and `/urls` work
+without React. hls.js loads on first play.
+
+## Client and providers
+
+```tsx
+import { createContentKitClient } from "@openrails/contentkit-ui/client";
+import { ContentKitProvider } from "@openrails/contentkit-ui/react";
+import { ContentKitUiProvider } from "@openrails/contentkit-ui";
+import { createContentURLs } from "@openrails/contentkit-ui/urls";
+
+const contentkit = createContentKitClient({
+  baseUrl: "/api/v1/contentkit",            // where the host mounts ContentKit
+  mounts: { upload: "/api/v1/user-uploads" }, // optional: modules mounted elsewhere (a string, or (ref) => string)
+  fetch: auth.authFetch,                    // an authenticating transport
+  token: () => auth.getAccessToken(),       // HLS playlists on the API origin (hls.js uses XHR)
+  language: () => lang,                     // Accept-Language
+});
+const urls = createContentURLs({ routes: { video: "watch", gallery: "g" }, languages: ["en", "es"], origin: "https://example.com" });
+
+<ContentKitProvider
+  client={contentkit}
+  viewer={user?.id ?? null}                 // the signed-in user as ContentKit sees it
+  language={lang}                          // same value as the client's language callback
+  accessRevision={accessRevision}          // increment when permissions/entitlements change
+  onSignIn={() => openSignIn()}             // asks signed-out visitors to sign in where the server refuses them
+  urls={urls}
+  navigate={(to, o) => navigate(to, o)}
+  onChange={(change) => queryClient.invalidateQueries({ queryKey: ["media", change.ref.id] })}
+  onError={(error, { operation }) => report(operation, error)}
+>
+  <ContentKitUiProvider appearance={{ theme: "inherit" }} language={lang} density={[2, 3]}>
+    <App />
+  </ContentKitUiProvider>
+</ContentKitProvider>;
+```
+
+Keep `viewer`, `language` and `accessRevision` current on the provider. A change
+starts fresh media and social reads without remounting the children. Old requests
+are abandoned when their last reader leaves; their results cannot fill the new
+scope. `accessRevision` is optional when the host has no changing access state.
+It is a cache signal, not an authorization decision. Without a provider, replace
+the client when its session or request language changes. Host-supplied `read` and
+`initial` data must also belong to the current viewer and language.
+
+Writes retain the cache scope they started in. After a scope change, a late
+notification refetches affected reads instead of copying its response into them;
+`onChange` still runs. Use a separate client for each independent session or
+request-language context, not one client across differently scoped providers.
+The framework-free client exposes `setReadScope(key)` and passes that key as
+the second `subscribe` / `onChange` argument, or `null` when the scope changed during the
+operation. This does not change the operation's result or its authentication.
+
+- **Mounts.** Without `mounts`, modules live under `baseUrl`: content at the
+  root, `/media` (reads, HLS), `/media/upload`, `/codes`, `/taxonomy`.
+- **`client.media`**: `upload`, `put` (upload, commit, wait), `commit`, `read`,
+  `waitFor`, `editorView`, `getFrame`, `hlsBase(ref, dir)`, `discard`, and
+  `xhrSetup` for players (`<MediaGallery xhrSetup={contentkit.media.xhrSetup} />`).
+  Uploads hash in a Web Worker, send one checksum-bound PUT up to 64 MiB and
+  resumable multipart above (`onState`/`resume`). The bucket must allow CORS
+  `PUT` from the app's origin with `Content-Type` and `x-amz-checksum-sha256`.
+- **Content modules**, one per resource, each method one route of the
+  generated route table with its generated types: `posts`, `comments`,
+  `reactions`, `favorites`, `polls`, `bans` (`"owner"` or `"global"`),
+  `moderation`, `taxonomy`, `codes`. Lists take `limit`/`offset` (the review
+  queue a `cursor`); staff lists are `posts.adminList` (`q` searches,
+  `deleted: true` lists deleted posts for `posts.restore`), `polls.adminList`,
+  `comments.adminList`.
+- **Images of posts and polls** go to the item's server-named upload path:
+  `media.uploadNamed(ref, file)` resolves the name content routes take;
+  `media.uploadInline(postId, file)` resolves a body image's public URL;
+  `posts.uploadCover`, `polls.uploadImage` and `polls.uploadOptionImage` do
+  both steps. `folders` renames the post and poll media kinds. A post's
+  public image files exist only while it is published; `usePost` shows an
+  unpublished post's images to its editors (below).
+- **`client.config()`** says what the content module allows: which
+  interactions signed-out visitors may make (`content.Options.Anonymous`,
+  none by default) and the longest comment (`CommentMaxLength`, 2,200 by
+  default; longer is `comment_too_long` with `details.max`).
+- **`client.subscribe(listener)`** receives every successful mutation
+  (`media.committed`, `media.processed`, `comment.created`, `reaction.changed`,
+  `poll.updated`, `ban.saved`, …); `ContentKitProvider onChange` is the same
+  stream, for the host's cache.
+- **`ContentKitProvider`** holds the client, URL config, `navigate`,
+  `onChange`, `onError` and the read store hooks share: one request per item
+  and options while any hook shows it; `set()` and processed uploads update
+  every reader in place.
+- **`ContentKitUiProvider`**: `appearance` (`theme`
+  `light`/`dark`/`auto`/`inherit`, `variables` as `--ckui-*`), `language`
+  (loads its built-in bundle), `messages` (bundles over it), `t` (host
+  translate hook), `density` (default `[2, 3]`), `inlinePreview` (default true).
+
+## Hooks
+
+Hooks read the client from `ContentKitProvider`; a `client` option overrides it.
+
+```tsx
+const q = useUploadQueue({ ref, path: "originals/{name}" });
+q.add(input.files!); q.move(id, 0); await q.commit();
+
+const one = useUpload();
+await one.upload(file, { ref, path: "inline/x.png", put: {} });
+
+const img = useSlotImage({ ref, path: "avatar", image });
+const crop = useSlotCrop({ ref, path: "avatar", file: img.file, aspect: "1:1", onSaved: img.set });
+```
+
+Content hooks share one store per client: one request per item while any
+hook shows it, kept per `viewer`, with every change made through the client
+applied in place. Reactions, favorites and votes apply at once and roll back
+if the server refuses them.
+
+```tsx
+const thread = useComments(ref, { sort: "best" });
+await thread.post("Nice!", { replyTo: parentId });
+await thread.react(comment, 1);
+const { counts, toggle } = useReaction(ref);
+const { favorited, count, toggle: fav } = useFavorite(ref);
+const { poll, vote } = usePoll(null, { language }); // the newest live poll
+const editor = usePollEditor(pollId);                // staff
+```
+
+A post editor puts `editorBody` in its rich-text field and inserts what
+`uploadImage(file)` resolves: URLs that show the images now (the file for a
+fresh upload, signed editor views of an unpublished post's images, read and
+refreshed as needed). `update({ body })` stores the images' public URLs
+(`storedBody(html)` does the same for a host's own save); `imageSrc(url)` shows
+the cover.
+
+```tsx
+const editor = usePost(postId);
+<RichText value={editor.editorBody} onImage={editor.uploadImage} onSave={(html) => editor.update({ body: html })} />
+<img src={editor.imageSrc(editor.post?.cover_url)} alt="" />
+```
+
+Also `useContentConfig` (`client.config()`, read once), `useCommentReplies`,
+`useCanComment` (may the caller comment, may signed-out visitors, the ban
+that stops it, and what it may do to others' comments), `useLatestComments`,
+`usePolls`, `usePosts` (staff: `admin`, `deleted`, `q`), `usePost` (with `restore`), and for staff `useAdminComments`,
+`useModerationQueue`, `useCommentBans`.
+
+Also: `useCrop`, `useVideoImages`, `useFrameStrip`, `useVideoFrame`,
+`useVideoPoster`, `useEncodeProgress`, `useHlsPlayer`, `useCarousel`,
+`useGalleryView`, `useInlinePreview`, `useRefreshBeforeExpiry`, `usePresets`,
+`useContentKitClient`, `useContentURLs`, `useErrorReporter`.
+
+### useMediaRead
+
+```tsx
+const { read, loading, error, processing, reload, refresh, set } =
+  useMediaRead(ref, { prefix: "low-res/", editor: true, window: { start: 0, end: 120 } });
+```
+
+One read per item and options, shared by every hook showing it. It reads
+again shortly before the URLs expire, waits out `rate_limited`, polls while
+uploads process (editor reads, every 2.5 s; `poll`), and reloads after any
+commit through the same client. `window` splits a long item into reads of
+`chunk` files (default 50) merged into one result; windows once read stay
+loaded. `refresh()` joins a read in flight (a player's grant refresh);
+`reload()` restarts it. `read` shows a host's read until `reload()`.
+
+### useMediaFolder
+
+```tsx
+const folder = useMediaFolder(ref, { paths: ["images/{name}", "videos/{name}"], commit: "manual" });
+folder.add(files);               // screened and queued; refusals in folder.refused
+await folder.commit();           // the uploaded files, in queue order
+await folder.move(path, 0); await folder.rename(path, "cover");
+await folder.edit(path, edit); await folder.replace(path, file); await folder.remove([path]);
+folder.discard();                // stop uploads and empty the queue
+```
+
+An item's folder for its editors: the editor read (all windows), an upload
+queue, and the kind's upload rules from the editor read, which screen type,
+size and file caps before anything uploads and name files around names
+taken. `groups` lists each path's uploads; `commit: "auto"` commits each
+upload once those before it have (a draft). Files added before the editor
+read arrives wait in `waiting` and are screened when its rules do (or
+refused if the read fails or states no rules). `ref` may be null until the item exists,
+so a composer can create its draft on the first drop. `busy` is true while
+work is in flight (files waiting, uploads queued or running, a commit or
+update); `fileCount` counts the uploads and the files on their way in. A
+committed file leaves the queue once the read lists it. Failures go to the provider's
+`onError` with an operation (`upload`, `folder.commit`, `folder.update`,
+`folder.process` for uploads the worker fails after the editor opened) and
+the file's name.
+
+### useEditorCrop
+
+```tsx
+const crop = useEditorCrop(ref, cropping); // a path, or null
+// crop.status: idle | loading | cropping (source, edit) | saving | done | error
+await crop.save(edit);
+```
+
+Re-crops a kept upload: while the path is set, its editor view (the
+original, oriented, unedited) and current edit load; `save` commits an edit
+op. Nothing is uploaded.
+
+### usePublicImage
+
+```tsx
+const { image, rule, isDefault } = usePublicImage("user", userId, "avatar");
+<SlotImage image={image} fallback={<Initials name={name} />} />
+```
+
+An item's image for a public preset: the exact renditions from a read's
+`public`, or from a host listing passed as `image` (no read), else the
+kind's default image. Published files carry a generation, so a URL built
+from a preset template only ever names the default; `rule` (from
+`GET /media/presets`) gives the shape, widths and narrowest edit.
+
+### useCanonicalContent
+
+```tsx
+useCanonicalContent(video.link, { title: video.title, image: posterURL, location: pathname + search, defaultLanguage: "en" });
+```
+
+Once a content page's link arrives, replaces the address with its canonical
+path (code spelling, merged code, current slug) through the provider's
+`navigate`, else `history.replaceState`, and keeps `<link rel=canonical>`,
+`og:url`, `og:title`, `og:image` and hreflang alternates (each language's
+own slug, plus `x-default`) in the head while mounted. Unmounting removes
+them, server-rendered ones included, so the next page sets its own. Needs the provider's
+`urls`; `/urls` also exports `hreflang()` and `canonicalURL()` (drops
+tracking parameters) for server rendering.
+
+### useNearViewport
+
+```tsx
+const [ref, near] = useNearViewport({ margin: "800px 0px", leaveMargin: "2400px 0px" });
+```
+
+Whether an element is near the viewport, to mount media as it approaches;
+with `leaveMargin`, false again far away.
+
+## Components
+
+`AvatarUpload`, `CoverUpload` (complete form fields); `SlotEditor` with
+`SlotEditMenu`, `SlotEditError` and `useSlotEditor()` (the same pick, crop,
+save and re-crop flow inside a host layout); `SlotImage`; `ImageCropDialog`;
+`VideoPosterPicker`, `VideoPoster`; `EncodeProgress`; `RenditionImg`;
+`MediaGallery`, `VideoPlayer` and `VideoMiniPlayer` (HLS with ABR, inline
+muted previews, a grant refresh before `expires`, and a reason, Retry and
+support code for every failure; see below). A `PublicPreset` (`{ preset, aspect, renditions }`)
+is what a slot or poster shows; a read's `public` lists `PublicImage`s. A
+slot crops at its image's aspect, else its public preset's
+(`GET /media/presets`), so an item without an image yet still crops a 3:1
+cover at 3:1.
+
+### MediaFolderEditor
+
+```tsx
+<MediaFolderEditor item={post} paths={["images/{name}", "videos/{name}"]} commit="auto" ref={handle}
+  toolbar={<ZipImport />} rowActions={(f) => <SetCover file={f} />} footer={note} />
+handle.current.discard();
+
+// Or the host owns the folder and renders with its state:
+const folder = useMediaFolder(draft, { paths, commit: "auto" }); // draft: null until created
+<MediaFolderEditor folder={folder} />
+<Button disabled={folder.busy || (!title && !text && !folder.fileCount)}>Publish</Button>
+```
+
+`useMediaFolder` with its UI: a drop zone stating the rules, a queue with
+progress, retry and remove, and each path's uploads as a sortable list with
+thumbnail, name, edited badge, encode progress and failure; crop (with
+`aspects` when the path has no preset shape), rename, replace and bulk
+remove. `commit="manual"` adds the queue with "Add N"; `"auto"` commits as
+files finish. `confirmRemove` replaces the browser's confirm.
+
+### SortableList
+
+```tsx
+<SortableList items={rows} id={(r) => r.id} name={(r) => r.title} onMove={(from, to) => move(from, to)} layout="grid">
+  {(row, handle) => <>{handle}<Row row={row} /></>}
+</SortableList>
+```
+
+Reorders by a drag handle with a mouse, a finger or the keyboard (Space or
+Enter lifts, arrows move, Space or Enter drops, Escape cancels), with
+localized screen reader announcements. `onMove` fires once, on drop.
+
+### ImageCropDialog shapes
+
+`aspects={["", "1:1", "4:5", "16:9"]}` adds a shape chooser (`""` is the
+original's, turning with the image); a preview of the result and its size
+sit under the controls (`preview={false}` hides them), and Reset returns to
+the starting shape and edit.
+
+### MediaGallery item
+
+`<MediaGallery item={post} prefix="low-res/" renderLocked={unlock} />` reads
+through the client: the read (refreshed, reloaded after commits), HLS bases,
+playlist auth and the grant refresh. Passing `read`, `hlsBase`, `xhrSetup`
+and `refresh` yourself still works. A locked item's public teaser carries
+the locked count and `renderLocked`, so the unlock is on the first slide;
+the stage is never taller than `maxHeight` (default `80svh`).
+
+### VideoPosterPicker frames from another video
+
+`frames={{ item: otherVideo, path: "source" }}` browses another item's video;
+the chosen frame (cropped or whole) is uploaded to the poster path as an
+image. Which video to offer is the host's choice.
+
+### HoverPreview
+
+```tsx
+<div className="card relative"><Thumbnail /><HoverPreview item={video} duration={video.duration} /></div>
+```
+
+A card's muted inline preview over the client's HLS base, fading in on hover
+(or while it is the most visible card on touch screens), one page-wide, off
+with reduced motion or Save-Data.
+
+### Images: fallback, skeleton, fit and LazyMount
+
+`RenditionImg`, `SlotImage` and `VideoPoster` take `fallback` (shown without
+renditions or after a failed load, e.g. a 404), and `RenditionImg` and
+`SlotImage` take `skeleton` (a pulsing fill until loaded) and `fit`
+(`cover` or `contain`). `<LazyMount placeholder={box}>` mounts its children
+as it nears the viewport (`useNearViewport` options).
+
+### MediaReadinessNotice
+
+`<MediaReadinessNotice item={post} description="Only editors see it until then." />`
+renders nothing once every upload is processed; while some process, a
+notice with the first video's encode progress; when uploads failed, which
+ones.
+
+## Video player
+
+`VideoPlayer` plays a ladder's HLS folder (`client.media.hlsBase(ref, dir)`)
+with its own controls: seek bar with sprite preview, volume, subtitles,
+audio, quality (Auto or a fixed rung), speed, picture in picture, theater,
+fullscreen and a mini player.
+
+```tsx
+<VideoPlayer
+  base={contentkit.media.hlsBase(ref, "hls/")}
+  xhrSetup={contentkit.media.xhrSetup}
+  refresh={reload} expires={read.expires}       // re-grant before the token expires
+  width={video.w} height={video.h} duration={video.dur} poster={posterPreset}
+  autoPlay startAt={resumePoint}                 // resume; never a muted autoplay
+  keyboard="global"                              // a watch page; default "focus"
+  audioLanguage={lang} subtitleLanguage={null}   // until the viewer chooses
+  onProgress={(p) => saveResume(p.time, p.played)} // interval, pause, seek, end, page hide, unload
+  onEvent={(e) => analytics(e)}                  // play, pause, seek, quality, audio, subtitles, fullscreen, error…
+  theater={theater} onTheaterChange={setTheater}
+  onMiniPlayer={setHandoff}
+  renderDownloads={({ className, container }) => <Downloads className={className} container={container} />}
+  menuItems={[{ label: "Version", value, options, onChange }, { label: "Report a problem", onSelect }]}
+/>
+{handoff && <VideoMiniPlayer handoff={handoff} xhrSetup={contentkit.media.xhrSetup} onExpand={openWatchPage} onClose={() => setHandoff(null)} />}
+```
+
+- **Shortcuts:** Space/K play, ←/→ 5 s, J/L 10 s, ↑/↓ volume, M mute, C
+  subtitles, F fullscreen, T theater, I mini player, 0–9 a tenth of the way,
+  Home/End, `<`/`>` speed. Never while typing or in a menu.
+- **Touch:** a tap shows or hides the controls; a double tap on either side
+  seeks 10 s, and further taps keep seeking. A double click is fullscreen.
+- **Remembered per browser:** volume and mute (`ckui.player.volume`), the
+  audio and subtitle languages (`ckui.player.tracks`) and a fixed quality
+  (`ckui.player.quality`); each `*Key` option renames or disables one.
+- **Mini player:** `onMiniPlayer` gets a `PlayerHandoff` (position, playing,
+  languages, size, poster). `VideoMiniPlayer` docks it in a corner and calls
+  `onExpand({ time, playing })` or `onClose({ time })`; where it lives and
+  what expand opens are the host's.
+- **Theming:** `appearance.variables.playerAccent` colors the played range
+  and pressed toggles (default white). Menus are always dark.
+
+## Comments, reactions and polls
+
+`Comments` (threads with one-level replies, tombstones, held and rejected
+states shown to their author, reactions, edit, delete, ban and rate-limit
+notices, the server's longest comment), `ReactionButtons`, `FavoriteButton` (with the server's count)
+and `Poll` (a final vote with results scaled to the leading option, or a
+free-text answer and its groups; `results="always"` shows results before
+voting). Signed-out visitors comment under a name, react and vote where the
+server allows it (`content.Options.Anonymous`, read from the comment standing
+and `client.config()`); elsewhere they are asked to sign in (`onSignIn`, the
+provider's or their own) or, without one, told to.
+
+Staff: `CommentModeration` (every comment, the review queue, the site's
+bans), `CommentBans` with `CommentBanDialog`, and `PollEditor`. They show what
+the caller's permissions allow and say so when a route refuses; the host
+decides who sees them.
+
+```tsx
+<Comments item={{ kind: "video", id }} count={video.comment_count} userHref={(u) => `/u/${u.username}`} />
+<Poll language={lang} />
+<CommentModeration contentKinds={["video", "post"]} itemHref={(i) => `/${i.kind}/${i.id}`} />
+```
+
+## Errors
+
+Every call rejects with `ContentKitError`: `code` (the server's, or `network`,
+`storage`, `aborted`, `resume_mismatch`, `decode`, `render_timeout`),
+`status`, `retryAfter`, `details` (image and video limits), `blobs`
+(`not_uploaded`), `ban` (`comment_banned`) and `action` (`rate_limited`),
+plus `refusal`, `isLimit`, `isCeiling`, `blocksQueue` and `transient`. Every
+code has a message in every bundle (`useMessages().error(e)`).
+
+## Migrating from the two old packages
+
+| Before | Now |
+| --- | --- |
+| `@openrails/contentkit-upload` | `@openrails/contentkit-ui/client` |
+| `@openrails/contentkit-upload/react` | `@openrails/contentkit-ui/react` |
+| `@openrails/contentkit-upload/ui` | `@openrails/contentkit-ui` |
+| `@openrails/contentkit-upload/locales/*`, `/styles.css` | `@openrails/contentkit-ui/locales/*`, `/styles.css` |
+| `@openrails/contentkit-urls` | `@openrails/contentkit-ui/urls` |
+| `createUploadClient({ endpoint, readEndpoint })` | `createContentKitClient({ baseUrl, mounts: { upload, media } }).media` |
+| `UploadClient`, `UploadApi` | `MediaClient`, `MediaApi` |
+| `UploadUiProvider client onError …` | `ContentKitProvider client onError` + `ContentKitUiProvider appearance messages t density inlinePreview` |
+| `UploadError`, `UploadErrorCode` | `ContentKitError`, `ContentKitErrorCode` |
+| `useUploadQueue(client, o)`, `useUpload(client)` | `useUploadQueue(o)`, `useUpload()` |
+| `useRead(client, ref, o)` | `useMediaRead(ref, o)` |
+| `useSlotImage(client, o)`, `useSlotCrop(client, o)` | `useSlotImage(o)`, `useSlotCrop(o)` |
+| `useVideoImages`, `useFrameStrip`, `useVideoFrame`, `useVideoPoster` `(client, o)` | the same `(o)` |
+| `PublicImage` (preset at an item) | `PublicPreset` |
+| `SlotImage`, `VideoPoster` `placeholder` | `fallback` |
+| `UploadUi*` types, `UploadUiRoot` | `ContentKitUi*`, `ContentKitUiRoot` |
+
+## Development
+
+```sh
+pnpm check                # typecheck, lint, unit tests (pure math and client-free components), build
+pnpm build
+pnpm test:e2e             # the integration project and the browser specs against a real ContentKit
+pnpm test:integration     # or either alone
+pnpm test:browser         # (demo/ in Chromium, light/dark × desktop/mobile screenshots)
+pnpm demo                 # the stack with seeded demo pages, until Ctrl-C
+```
+
+The suites need Docker, Go and ffmpeg. `e2e/server` composes the real
+`contentkit.Runtime` (content, taxonomy, codes, media upload and read) with
+AuthKit for identity over PGroonga PostgreSQL 18, MinIO, and media-worker and
+media-gateway built from this checkout (`e2e/compose.yaml`). Each run brings
+the stack up under its own project name and takes it down; the server exits
+with its runner. Pages sign in with auth-ui and pass `auth.authFetch`. Tests
+set up through `/__test`: accounts (`staff`, `moderator`, `editor` roles),
+items the host's resolver knows, stored-object checks, and faults (no CORS,
+429 and expired tokens at the gateway, dropped or held bucket requests, API
+error replies).
+
+The wire types, route table and error codes in `src/client/generated/` are
+generated from ContentKit's route catalog (`pnpm contract`; CI runs
+`pnpm contract:check`). UI primitives come from
+`pnpm dlx shadcn@4.21.0 add …` (`components.json`); local edits are marked
+`// Local:`. The `release` workflow publishes the package to npm for every
+published `v*` release.

package/dist/appearance.d.ts

@@ -0,0 +1,38 @@
+import { CSSProperties } from 'react';
+/**
+ * `light`/`dark` force a palette, `auto` follows the OS, `inherit` reads the
+ * host's shadcn tokens (`--primary`, …) and its `.dark` class.
+ */
+export type ContentKitUiTheme = "light" | "dark" | "auto" | "inherit";
+/** Raw CSS values applied as `--ckui-*` custom properties on every root. */
+export interface ContentKitUiVariables {
+    background?: string;
+    foreground?: string;
+    card?: string;
+    cardForeground?: string;
+    popover?: string;
+    popoverForeground?: string;
+    primary?: string;
+    primaryForeground?: string;
+    secondary?: string;
+    secondaryForeground?: string;
+    muted?: string;
+    mutedForeground?: string;
+    accent?: string;
+    accentForeground?: string;
+    destructive?: string;
+    warning?: string;
+    border?: string;
+    input?: string;
+    ring?: string;
+    radius?: string;
+    fontFamily?: string;
+    /** The video player's played range, seek thumb and pressed toggles. Default white. */
+    playerAccent?: string;
+}
+export interface ContentKitUiAppearance {
+    theme?: ContentKitUiTheme;
+    variables?: ContentKitUiVariables;
+}
+export declare function appearanceStyle(a: ContentKitUiAppearance | undefined): CSSProperties | undefined;
+export declare function appearanceTheme(a: ContentKitUiAppearance | undefined): ContentKitUiTheme;

package/dist/appearance.js

@@ -0,0 +1,15 @@
+//#region src/appearance.ts
+var e = (e) => e.replace(/[A-Z]/g, (e) => "-" + e.toLowerCase());
+function t(t) {
+	if (!t?.variables) return;
+	let n = {};
+	for (let [r, i] of Object.entries(t.variables)) i && (n[r === "fontFamily" ? "--ckui-font" : `--ckui-${e(r)}`] = i);
+	return n;
+}
+function n(e) {
+	return e?.theme ?? "auto";
+}
+//#endregion
+export { t as appearanceStyle, n as appearanceTheme };
+
+//# sourceMappingURL=appearance.js.map

package/dist/appearance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"appearance.js","names":[],"sources":["../src/appearance.ts"],"sourcesContent":["import type { CSSProperties } from \"react\";\n\n/**\n * `light`/`dark` force a palette, `auto` follows the OS, `inherit` reads the\n * host's shadcn tokens (`--primary`, …) and its `.dark` class.\n */\nexport type ContentKitUiTheme = \"light\" | \"dark\" | \"auto\" | \"inherit\";\n\n/** Raw CSS values applied as `--ckui-*` custom properties on every root. */\nexport interface ContentKitUiVariables {\n  background?: string;\n  foreground?: string;\n  card?: string;\n  cardForeground?: string;\n  popover?: string;\n  popoverForeground?: string;\n  primary?: string;\n  primaryForeground?: string;\n  secondary?: string;\n  secondaryForeground?: string;\n  muted?: string;\n  mutedForeground?: string;\n  accent?: string;\n  accentForeground?: string;\n  destructive?: string;\n  warning?: string;\n  border?: string;\n  input?: string;\n  ring?: string;\n  radius?: string;\n  fontFamily?: string;\n  /** The video player's played range, seek thumb and pressed toggles. Default white. */\n  playerAccent?: string;\n}\n\nexport interface ContentKitUiAppearance {\n  theme?: ContentKitUiTheme;\n  variables?: ContentKitUiVariables;\n}\n\nconst kebab = (k: string) => k.replace(/[A-Z]/g, (c) => \"-\" + c.toLowerCase());\n\nexport function appearanceStyle(a: ContentKitUiAppearance | undefined): CSSProperties | undefined {\n  if (!a?.variables) return undefined;\n  const style: Record<string, string> = {};\n  for (const [key, value] of Object.entries(a.variables)) {\n    if (value) style[key === \"fontFamily\" ? \"--ckui-font\" : `--ckui-${kebab(key)}`] = value;\n  }\n  return style as CSSProperties;\n}\n\nexport function appearanceTheme(a: ContentKitUiAppearance | undefined): ContentKitUiTheme {\n  return a?.theme ?? \"auto\";\n}\n"],"mappings":";AAwCA,IAAM,KAAS,MAAc,EAAE,QAAQ,WAAW,MAAM,MAAM,EAAE,YAAY,CAAC;AAE7E,SAAgB,EAAgB,GAAkE;CAChG,IAAI,CAAC,GAAG,WAAW;CACnB,IAAM,IAAgC,CAAC;CACvC,KAAK,IAAM,CAAC,GAAK,MAAU,OAAO,QAAQ,EAAE,SAAS,GACnD,AAAI,MAAO,EAAM,MAAQ,eAAe,gBAAgB,UAAU,EAAM,CAAG,OAAO;CAEpF,OAAO;AACT;AAEA,SAAgB,EAAgB,GAA0D;CACxF,OAAO,GAAG,SAAS;AACrB"}