@letterncms/sdk 0.0.0-stage → 0.1.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Falko Joseph
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,21 @@
 {
-  "name": "@letterncms/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@letterncms/sdk",
+    "description": "The admin's API client, ability hooks, router and extension registry. The admin provides the code at runtime.",
+    "exports": {
+        ".": "./src/index.ts"
+    },
+    "peerDependencies": {
+        "react": "^19.0.0",
+        "@tanstack/react-query": "^5.0.0"
+    },
+    "version": "0.1.1",
+    "type": "module",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/letterncms/cms.git"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}

package/src/api.ts

@@ -0,0 +1,154 @@
+import { t } from './i18n'
+import type { Boot } from './types'
+
+declare global {
+  interface Window {
+    __CMS__: Boot
+  }
+}
+
+export const boot: Boot = (typeof window !== 'undefined' && window.__CMS__) || {
+  base: '/admin',
+  api: '/api/admin',
+  version: 'dev',
+  brand: { name: '', domain: '', product_url: '', docs_url: '', github_url: '', support_email: '', mark: '', wordmark: '' },
+  site: { name: '', url: '' },
+}
+
+/** Error thrown for any failed request; mirrors the server's AbilityException. */
+export class CmsError extends Error {
+  constructor(
+    message: string,
+    public readonly type: string = 'failed',
+    public readonly status: number = 500,
+    public readonly details: Record<string, string> = {},
+  ) {
+    super(message)
+    this.name = 'CmsError'
+  }
+}
+
+/** The token to send with a request that changes something. The cookie's name is the site's own, as cookies don't tell ports apart. */
+export function xsrfToken(): string | null {
+  const name = boot.xsrfCookie ?? 'XSRF-TOKEN'
+  const cookie = document.cookie.split(/;\s*/).find((part) => part.startsWith(`${name}=`))
+  return cookie ? decodeURIComponent(cookie.slice(name.length + 1)) : null
+}
+
+let unauthorizedHandler: (() => void) | null = null
+
+/** Called whenever the session expires (401) so the theme can show the sign-in screen. */
+export function onUnauthorized(handler: () => void) {
+  unauthorizedHandler = handler
+}
+
+function headers(accept: string, json: boolean): Record<string, string> {
+  const h: Record<string, string> = { Accept: accept, 'X-Requested-With': 'XMLHttpRequest' }
+  const token = xsrfToken()
+  if (token) h['X-XSRF-TOKEN'] = token
+  if (json) h['Content-Type'] = 'application/json'
+  // The language this page was opened in (it may differ from the account's: `?lang=nl`).
+  if (boot.locale) h['X-Cms-Locale'] = boot.locale
+  return h
+}
+
+function failure(response: Response, json: any): CmsError {
+  if (response.status === 401 && unauthorizedHandler) unauthorizedHandler()
+  const error = json?.error
+  const laravelErrors = json?.errors ? Object.fromEntries(Object.entries(json.errors).map(([k, v]) => [k, (v as string[])[0]])) : {}
+  return new CmsError(
+    error?.message ?? json?.message ?? (response.status === 419 ? t('Your session expired. Reload the page.') : t('Request failed ({status})', { status: response.status })),
+    error?.type ?? (response.status === 422 ? 'invalid_input' : 'failed'),
+    response.status,
+    error?.details ?? laravelErrors,
+  )
+}
+
+const apiUrl = (path: string) => (path.startsWith('/') ? path : `${boot.api}/${path}`)
+
+export async function request<T = unknown>(method: string, path: string, body?: unknown, init: RequestInit = {}): Promise<T> {
+  const response = await fetch(apiUrl(path), {
+    method,
+    credentials: 'same-origin',
+    headers: { ...headers('application/json', body !== undefined && !(body instanceof FormData)), ...(init.headers as Record<string, string> | undefined) },
+    body: body === undefined ? undefined : body instanceof FormData ? body : JSON.stringify(body),
+    ...init,
+  })
+
+  const text = await response.text()
+  const json = text ? safeJson(text) : null
+
+  if (!response.ok) throw failure(response, json)
+
+  return json as T
+}
+
+/**
+ * POST that answers with server-sent events. Calls onEvent for every event as
+ * it arrives and resolves when the stream ends; abort with the signal.
+ */
+export async function eventStream(path: string, body: unknown, onEvent: (event: string, data: any) => void, signal?: AbortSignal): Promise<void> {
+  const response = await fetch(apiUrl(path), {
+    method: 'POST',
+    credentials: 'same-origin',
+    headers: headers('text/event-stream', true),
+    body: JSON.stringify(body),
+    signal,
+  })
+
+  if (!response.ok || !response.body || !(response.headers.get('Content-Type') ?? '').startsWith('text/event-stream')) {
+    const text = await response.text()
+    throw failure(response.ok ? new Response(null, { status: 500 }) : response, text ? safeJson(text) : null)
+  }
+
+  const reader = response.body.pipeThrough(new TextDecoderStream()).getReader()
+  let buffer = ''
+
+  for (;;) {
+    const { value, done } = await reader.read()
+    if (done) break
+    buffer += value.replace(/\r\n/g, '\n')
+
+    let end: number
+    while ((end = buffer.indexOf('\n\n')) >= 0) {
+      const chunk = buffer.slice(0, end)
+      buffer = buffer.slice(end + 2)
+      let event = 'message'
+      const data: string[] = []
+      for (const line of chunk.split('\n')) {
+        if (line.startsWith('event:')) event = line.slice(6).trim()
+        else if (line.startsWith('data:')) data.push(line.slice(5).replace(/^ /, ''))
+      }
+      if (data.length) onEvent(event, safeJson(data.join('\n')))
+    }
+  }
+}
+
+function safeJson(text: string): any {
+  try {
+    return JSON.parse(text)
+  } catch {
+    return null
+  }
+}
+
+/** Run an ability as the signed-in user. Resolves with the ability's result. */
+export async function run<T = any>(ability: string, input: Record<string, unknown> = {}): Promise<T> {
+  const res = await request<{ data: T }>('POST', `abilities/${ability}`, input)
+  return res.data
+}
+
+export interface BatchCall {
+  ability: string
+  input?: Record<string, unknown>
+}
+
+export async function batch(calls: BatchCall[], stopOnError = true): Promise<({ data: any } | { error: { type: string; message: string } })[]> {
+  const res = await request<{ data: any[] }>('POST', 'batch', { calls, stopOnError })
+  return res.data
+}
+
+/** Absolute admin URL for a path inside the admin. */
+export function adminUrl(path = '/'): string {
+  return boot.base + (path === '/' ? '' : path.startsWith('/') ? path : `/${path}`)
+}

package/src/events.ts

@@ -0,0 +1,14 @@
+type Handler<T = any> = (payload: T) => void
+const handlers = new Map<string, Set<Handler>>()
+
+/** Tiny event bus for loose coupling between the theme and plugin modules. */
+export const events = {
+  on<T = any>(name: string, handler: Handler<T>): () => void {
+    if (!handlers.has(name)) handlers.set(name, new Set())
+    handlers.get(name)!.add(handler)
+    return () => handlers.get(name)?.delete(handler)
+  },
+  emit<T = any>(name: string, payload?: T) {
+    handlers.get(name)?.forEach((h) => h(payload))
+  },
+}

package/src/i18n.ts

@@ -0,0 +1,49 @@
+import { boot } from './api'
+
+/**
+ * The admin speaks the user's language. Labels are written in English and are their
+ * own key; core and every package ship `lang/<code>.json` dictionaries, merged by the
+ * server and handed over at boot. A missing translation shows the English text.
+ * Write English labels, headings and actions in title case ("Design System");
+ * descriptions, instructions and messages use sentence case. Translations follow
+ * the capitalization conventions of their language.
+ *
+ *   t('Publish')                             → "Publiceren"
+ *   t('Delete “{title}”?', { title })        → placeholders in braces
+ *   plural(count, '{count} entry', '{count} entries')
+ *   {brand} in any string                    → the product's name, without passing it
+ */
+// Read from boot on first use: api.ts translates its own errors, so the two modules import each other.
+let messages: Record<string, string> | null = null
+let current: string | null = null
+const dictionary = () => (messages ??= (boot.messages as Record<string, string> | undefined) ?? {})
+
+export function t(text: string, params?: Record<string, string | number | null | undefined>): string {
+  const translated = dictionary()[text] || text
+  if (!translated.includes('{')) return translated
+  const values: Record<string, string | number | null | undefined> = { brand: boot.brand?.name, ...params }
+  return translated.replace(/\{(\w+)\}/g, (match, key: string) => (values[key] === undefined || values[key] === null ? match : String(values[key])))
+}
+
+/** The singular or plural form for a count, translated, with `{count}` filled in. */
+export function plural(count: number, one: string, other: string, params?: Record<string, string | number | null | undefined>): string {
+  const form = new Intl.PluralRules(locale()).select(count) === 'one' ? one : other
+  return t(form, { count: count.toLocaleString(locale()), ...params })
+}
+
+/** The admin's language (a code like `nl`). Dates and numbers follow it. */
+export function locale(): string {
+  return (current ??= boot.locale ?? 'en')
+}
+
+/** The languages the admin speaks: code → name in that language. */
+export function languages(): Record<string, string> {
+  return boot.languages ?? { en: 'English' }
+}
+
+/** Switch the dictionary (after the user picks another language). */
+export function setLocale(code: string, dictionary: Record<string, string>) {
+  current = code
+  messages = dictionary
+  document.documentElement.lang = code
+}

package/src/index.ts

@@ -0,0 +1,29 @@
+import { locale } from './i18n'
+
+export * from './types'
+export { boot, request, eventStream, run, batch, adminUrl, CmsError, onUnauthorized, xsrfToken } from './api'
+export type { BatchCall } from './api'
+export { navigate, useLocation, useScreenLocation, ScreenLocation, useTab, matchPath, setQuery, Link, blockNavigation, prefetch, onLinkIntent } from './router'
+export type { LinkProps, Location } from './router'
+export { queryClient, useAbility, useAction, invalidate, abilityKey, prefetchAbility } from './query'
+export { loadManifest, setManifest, onManifest, getManifest, useManifest, useManifestIfLoaded, useConfig, isActive, can, brand } from './manifest'
+export { registry, panelsFor, registerAs, unregister, reregister } from './registry'
+export type { RouteDef, PanelDef, CommandDef, Registrations } from './registry'
+export { events } from './events'
+export { t, plural, locale, languages, setLocale } from './i18n'
+
+/** Human-readable relative time ("3 min ago"). */
+export function timeAgo(iso: string | null | undefined): string {
+  if (!iso) return ''
+  const seconds = Math.round((Date.now() - new Date(iso).getTime()) / 1000)
+  const rtf = new Intl.RelativeTimeFormat(locale(), { numeric: 'auto', style: 'short' })
+  const steps: [number, Intl.RelativeTimeFormatUnit][] = [[60, 'second'], [3600, 'minute'], [86400, 'hour'], [604800, 'day'], [2629800, 'week'], [31557600, 'month'], [Infinity, 'year']]
+  // A moment ago is "now"; past that, whole units only (23 hours, not a rounded-up "24 hr.", then "yesterday").
+  if (Math.abs(seconds) < 45) return rtf.format(0, 'second')
+  let previous = 1
+  for (const [limit, unit] of steps) {
+    if (Math.abs(seconds) < limit) return rtf.format(-Math.trunc(seconds / previous), unit)
+    previous = limit
+  }
+  return ''
+}

package/src/manifest.ts

@@ -0,0 +1,96 @@
+import { useSyncExternalStore } from 'react'
+import { boot, request } from './api'
+import type { BrandInfo, Manifest } from './types'
+
+let manifest: Manifest | null = null
+const listeners = new Set<() => void>()
+
+function publish(next: Manifest) {
+  manifest = next
+  listeners.forEach((l) => l())
+}
+
+/**
+ * Fetch the manifest again. Call it after changing anything it describes (packages,
+ * collections, the sidebar…): the admin follows along — new modules load, the
+ * modules of packages turned off leave, the sidebar redraws — without a reload.
+ */
+export async function loadManifest(): Promise<Manifest> {
+  const res = await request<{ data: Manifest }>('GET', 'manifest')
+  publish(res.data)
+  return res.data
+}
+
+/** Use a manifest the server already sent along (the admin page embeds it at boot). */
+export function setManifest(next: Manifest) {
+  publish(next)
+}
+
+/** Be told whenever the manifest changes (admin themes follow it to load and unload modules). */
+export function onManifest(listener: (manifest: Manifest) => void): () => void {
+  const l = () => manifest && listener(manifest)
+  listeners.add(l)
+  return () => {
+    listeners.delete(l)
+  }
+}
+
+/** The product's display name, links and images: never write the name in a string. In a translated string use `{brand}`. */
+export function brand(): BrandInfo {
+  return manifest?.brand ?? boot.brand
+}
+
+export function getManifest(): Manifest {
+  if (!manifest) throw new Error('Manifest not loaded yet.')
+  return manifest
+}
+
+/** The manifest, or null before sign-in (forms like sign-in render without it). */
+export function useManifestIfLoaded(): Manifest | null {
+  return useSyncExternalStore(
+    (l) => {
+      listeners.add(l)
+      return () => listeners.delete(l)
+    },
+    () => manifest,
+  )
+}
+
+export function useManifest(): Manifest {
+  const m = useSyncExternalStore(
+    (l) => {
+      listeners.add(l)
+      return () => listeners.delete(l)
+    },
+    () => manifest,
+  )
+  if (!m) throw new Error('Manifest not loaded yet.')
+  return m
+}
+
+/**
+ * A module's values that every admin user may read (e.g. letterncms/content's page size),
+ * as the module put them in the manifest under `config.<namespace>`.
+ */
+export function useConfig<T extends Record<string, unknown> = Record<string, any>>(namespace: string): Partial<T> {
+  return (useManifest().config?.[namespace] ?? {}) as Partial<T>
+}
+
+/** True when a package (module, plugin or theme) is active on this site. */
+export function isActive(pkg: string): boolean {
+  return manifest?.packages.active.includes(pkg) ?? false
+}
+
+/** Wildcard-aware permission check against the signed-in user's grants. */
+export function can(permission: string, any = false): boolean {
+  if (!manifest) return false
+  const { user } = manifest
+  if (user.super) return true
+  return user.grants.some((grant) => grant === '*' || glob(grant, permission) || (any && glob(permission, grant)))
+}
+
+function glob(pattern: string, value: string): boolean {
+  if (pattern === value) return true
+  const regex = new RegExp('^' + pattern.split('*').map((s) => s.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('.*') + '$')
+  return regex.test(value)
+}

package/src/query.ts

@@ -0,0 +1,57 @@
+import { QueryClient, useMutation, useQuery, type UseQueryOptions } from '@tanstack/react-query'
+import { CmsError, run } from './api'
+
+export const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 15_000,
+      retry: (count, error) => !(error instanceof CmsError && [401, 403, 404, 422].includes(error.status)) && count < 2,
+      refetchOnWindowFocus: true,
+    },
+    mutations: { retry: false },
+  },
+})
+
+/** Query keys are [ability, input] so mutations can invalidate by ability prefix. */
+export function abilityKey(ability: string, input?: Record<string, unknown>) {
+  return input === undefined ? [ability] : [ability, input]
+}
+
+/** Prepare a screen's data using the same cache as useAbility; cached data opens immediately. */
+export function prefetchAbility<T = any>(ability: string, input: Record<string, unknown> = {}): Promise<T> {
+  return queryClient.ensureQueryData<T>({ queryKey: abilityKey(ability, input), queryFn: () => run<T>(ability, input) })
+}
+
+/** Read data through a (read-only) ability. */
+export function useAbility<T = any>(
+  ability: string,
+  input: Record<string, unknown> = {},
+  options: Omit<UseQueryOptions<T, CmsError>, 'queryKey' | 'queryFn'> = {},
+) {
+  return useQuery<T, CmsError>({ queryKey: abilityKey(ability, input), queryFn: () => run<T>(ability, input), ...options })
+}
+
+/**
+ * Change data through an ability. `invalidates` lists ability prefixes whose
+ * cached results become stale, e.g. ['entries/'].
+ */
+export function useAction<T = any, I extends Record<string, unknown> = Record<string, unknown>>(
+  ability: string,
+  options: { invalidates?: string[]; onSuccess?: (data: T, input: I) => void; onError?: (error: CmsError) => void } = {},
+) {
+  return useMutation<T, CmsError, I>({
+    mutationFn: (input: I) => run<T>(ability, input),
+    onSuccess: (data, input) => {
+      invalidate(...(options.invalidates ?? []))
+      options.onSuccess?.(data, input)
+    },
+    onError: options.onError,
+  })
+}
+
+export function invalidate(...prefixes: string[]) {
+  if (prefixes.length === 0) return
+  void queryClient.invalidateQueries({
+    predicate: (q) => typeof q.queryKey[0] === 'string' && prefixes.some((p) => (q.queryKey[0] as string).startsWith(p)),
+  })
+}

package/src/registry.ts

@@ -0,0 +1,159 @@
+import type { ComponentType } from 'react'
+import type { FieldProps, SurfaceComponentProps } from './types'
+import type { Location } from './router'
+
+export interface RouteDef {
+  path: string
+  component: ComponentType<{ params: Record<string, string> }>
+  /** Prime required queries before showing this screen. Also called on link intent. */
+  load?: (params: Record<string, string>, location: Location) => Promise<unknown>
+  /** "default" renders inside the shell; "full" takes the whole window (editors). */
+  layout?: 'default' | 'full'
+  title?: string
+}
+
+export interface PanelDef<P = any> {
+  id: string
+  slot: string
+  /** Tab label for sidebar panels. */
+  label?: string
+  icon?: string
+  component: ComponentType<P>
+  order?: number
+  when?: (props: P) => boolean
+  /** Entry field handles edited by this applicable panel. Unclaimed fields use the standard form. */
+  fieldHandles?: string[]
+}
+
+export interface CommandDef {
+  id: string
+  label: string
+  icon?: string
+  group?: string
+  keywords?: string[]
+  shortcut?: string
+  /** When true the palette offers this command for any typed text and passes it in (e.g. "Ask the CMS …"). */
+  acceptsQuery?: boolean
+  perform: (query?: string) => void | Promise<void>
+}
+
+type Listener = () => void
+
+/** The module whose code is running right now (see `registerAs`); what it registers is attributed to it. */
+let owner: string | null = null
+
+interface Layer<T> {
+  owner: string | null
+  value: T
+}
+
+/**
+ * A keyed store where a later registration of the same key wins, and taking a
+ * module's registrations back reveals what it had replaced.
+ */
+function store<T>() {
+  const layers = new Map<string, Layer<T>[]>()
+  const listeners = new Set<Listener>()
+  let version = 0
+  const changed = () => {
+    version++
+    listeners.forEach((l) => l())
+  }
+  const top = (key: string) => {
+    const stack = layers.get(key)
+    return stack?.[stack.length - 1]
+  }
+  return {
+    set(key: string, value: T) {
+      const stack = (layers.get(key) ?? []).filter((layer) => layer.owner !== owner)
+      stack.push({ owner, value })
+      layers.set(key, stack)
+      changed()
+    },
+    delete(key: string) {
+      layers.delete(key)
+      changed()
+    },
+    get: (key: string) => top(key)?.value,
+    all: () => [...layers.keys()].map((key) => top(key)!.value),
+    entries: () => [...layers.keys()].map((key) => [key, top(key)!.value] as [string, T]),
+    subscribe(l: Listener) {
+      listeners.add(l)
+      return () => listeners.delete(l)
+    },
+    version: () => version,
+    /** @internal Remove what a module registered; returns it so it can be put back. */
+    withdraw(id: string): [string, T][] {
+      const taken: [string, T][] = []
+      for (const [key, stack] of layers) {
+        const kept = stack.filter((layer) => {
+          if (layer.owner !== id) return true
+          taken.push([key, layer.value])
+          return false
+        })
+        if (kept.length === stack.length) continue
+        if (kept.length) layers.set(key, kept)
+        else layers.delete(key)
+      }
+      if (taken.length) changed()
+      return taken
+    },
+    /** @internal Put back what `withdraw` took. */
+    restore(id: string, entries: [string, T][]) {
+      for (const [key, value] of entries) layers.set(key, [...(layers.get(key) ?? []).filter((layer) => layer.owner !== id), { owner: id, value }])
+      if (entries.length) changed()
+    },
+  }
+}
+
+/**
+ * Extension points for plugins. Admin themes read from here; plugins write.
+ *
+ *   registry.routes.set('/media', { path: '/media', component: MediaLibrary })
+ *   registry.fields.set('media', MediaField)
+ *   registry.panels.set('seo', { id: 'seo', slot: 'entry.sidebar', component: SeoPanel })
+ */
+export const registry = {
+  routes: store<RouteDef>(),
+  fields: store<ComponentType<FieldProps>>(),
+  panels: store<PanelDef>(),
+  widgets: store<ComponentType<{ id: string }>>(),
+  components: store<ComponentType<SurfaceComponentProps<any>>>(),
+  commands: store<CommandDef>(),
+  icons: store<string>(),
+}
+
+type Stores = typeof registry
+export type Registrations = { [K in keyof Stores]: ReturnType<Stores[K]['withdraw']> }
+
+/**
+ * Run a module's code (its import and setup) with everything it registers
+ * attributed to it, so the admin can take it back when its package is turned
+ * off. Admin themes load modules through this, one at a time.
+ */
+export async function registerAs(id: string, load: () => unknown): Promise<void> {
+  const previous = owner
+  owner = id
+  try {
+    await load()
+  } finally {
+    owner = previous
+  }
+}
+
+/** Take back everything a module registered. Returns it, for `reregister` when the module comes back. */
+export function unregister(id: string): Registrations {
+  return Object.fromEntries(Object.entries(registry).map(([name, s]) => [name, s.withdraw(id)])) as Registrations
+}
+
+/** Put a module's registrations back (an ES module runs once per page, so turning it on again restores what it registered). */
+export function reregister(id: string, registrations: Registrations) {
+  for (const [name, entries] of Object.entries(registrations)) registry[name as keyof Stores].restore(id, entries as never)
+}
+
+/** Panels for a slot, ordered. */
+export function panelsFor<P>(slot: string, props: P): PanelDef<P>[] {
+  return (registry.panels.all() as PanelDef<P>[])
+    .filter((p) => p.slot === slot && (!p.when || p.when(props)))
+    .sort((a, b) => (a.order ?? 50) - (b.order ?? 50))
+}

package/src/router.tsx

@@ -0,0 +1,201 @@
+import { createContext, createElement, useContext, useDeferredValue, useEffect, useMemo, useState, useSyncExternalStore, type AnchorHTMLAttributes, type FocusEvent, type MouseEvent, type ReactNode } from 'react'
+import { boot } from './api'
+
+type Listener = () => void
+const listeners = new Set<Listener>()
+let blockers: (() => string | null)[] = []
+
+/** Where the admin is. `action` says how it got there: a link (push), a redirect (replace) or back/forward (pop). */
+export interface Location {
+  path: string
+  search: string
+  query: Record<string, string>
+  action: 'push' | 'replace' | 'pop'
+}
+
+interface Snapshot {
+  path: string
+  search: string
+  action: Location['action']
+}
+
+function currentPath(): string {
+  const path = window.location.pathname.startsWith(boot.base) ? window.location.pathname.slice(boot.base.length) : window.location.pathname
+  return path === '' ? '/' : path
+}
+
+let snapshot: Snapshot = { path: currentPath(), search: window.location.search, action: 'pop' }
+
+function update(action: Snapshot['action']) {
+  snapshot = { path: currentPath(), search: window.location.search, action }
+  listeners.forEach((l) => l())
+}
+
+window.addEventListener('popstate', () => update('pop'))
+
+const subscribe = (l: Listener) => {
+  listeners.add(l)
+  return () => {
+    listeners.delete(l)
+  }
+}
+
+const useSnapshot = () => useSyncExternalStore(subscribe, () => snapshot)
+
+/** The location screens see: the one they were drawn for, while the next screen gets ready. */
+const ScreenContext = createContext<Location | null>(null)
+
+/** Register a guard (e.g. unsaved changes). Return a message to block navigation. */
+export function blockNavigation(check: () => string | null): () => void {
+  blockers.push(check)
+  return () => {
+    blockers = blockers.filter((b) => b !== check)
+  }
+}
+
+function blocked(): boolean {
+  for (const check of blockers) {
+    const message = check()
+    if (message && !window.confirm(message)) return true
+  }
+  return false
+}
+
+export function navigate(to: string, options: { replace?: boolean } = {}) {
+  if (/^https?:\/\//.test(to)) {
+    window.location.href = to
+    return
+  }
+  if (blocked()) return
+  const url = boot.base + (to === '/' ? '' : to)
+  if (options.replace) window.history.replaceState(null, '', url)
+  else window.history.pushState(null, '', url)
+  update(options.replace ? 'replace' : 'push')
+}
+
+function toLocation(s: Snapshot): Location {
+  return { path: s.path, search: s.search, query: Object.fromEntries(new URLSearchParams(s.search)), action: s.action }
+}
+
+export function useLocation(): Location {
+  const screen = useContext(ScreenContext)
+  const live = useSnapshot()
+  const location = useMemo(() => toLocation(live), [live])
+  return screen ?? location
+}
+
+/**
+ * For admin themes: the location to draw the screen for. Going to another path
+ * keeps the current screen on view until the next one is ready (code and data),
+ * so navigating never flashes a loading state; changes to the query apply at once.
+ * Wrap the screen in `<ScreenLocation>` with it, so the screen reads it too.
+ */
+export function useScreenLocation(prepare?: (location: Location) => Promise<unknown>): { location: Location; pending: boolean } {
+  const live = useSnapshot()
+  const [ready, setReady] = useState(live)
+  useEffect(() => {
+    if (!prepare) return
+    if (live.path === ready.path) {
+      setReady(live)
+      return
+    }
+    let canceled = false
+    // A later navigation wins, even if an earlier request finishes last. Failures
+    // still open the destination so its normal error/retry UI can handle them.
+    void Promise.resolve().then(() => prepare(toLocation(live))).catch(() => {}).then(() => {
+      if (!canceled) setReady(live)
+    })
+    return () => { canceled = true }
+  }, [live, ready.path, prepare])
+  const target = !prepare || live.path === ready.path ? live : ready
+  const deferred = useDeferredValue(target)
+  const s = deferred.path === live.path ? live : deferred
+  const location = useMemo(() => toLocation(s), [s])
+  return { location, pending: s !== live }
+}
+
+export function ScreenLocation({ location, children }: { location: Location; children: ReactNode }) {
+  return createElement(ScreenContext.Provider, { value: location }, children)
+}
+
+let prefetcher: ((path: string) => void) | null = null
+
+/** For admin themes: called when a link is about to be followed (hovered or focused), to get its screen ready. */
+export function onLinkIntent(handler: (path: string) => void) {
+  prefetcher = handler
+}
+
+/** Get a screen's code and required data ready, e.g. when a menu item is highlighted. */
+export function prefetch(path: string) {
+  if (!/^https?:\/\//.test(path)) prefetcher?.(path)
+}
+
+/** Match "/collections/:handle/*" against a path. */
+export function matchPath(pattern: string, path: string): Record<string, string> | null {
+  const p = pattern.split('/').filter(Boolean)
+  const s = path.split('/').filter(Boolean)
+  const params: Record<string, string> = {}
+
+  for (let i = 0; i < p.length; i++) {
+    const part = p[i]
+    if (part === '*') {
+      params['*'] = s.slice(i).map(decodeURIComponent).join('/')
+      return params
+    }
+    if (i >= s.length) return null
+    if (part.startsWith(':')) params[part.slice(1)] = decodeURIComponent(s[i])
+    else if (part !== s[i]) return null
+  }
+
+  return s.length === p.length ? params : null
+}
+
+export function setQuery(values: Record<string, string | number | null | undefined>, replace = true) {
+  const params = new URLSearchParams(window.location.search)
+  for (const [k, v] of Object.entries(values)) {
+    if (v === null || v === undefined || v === '') params.delete(k)
+    else params.set(k, String(v))
+  }
+  const qs = params.toString()
+  const url = window.location.pathname + (qs ? `?${qs}` : '')
+  replace ? window.history.replaceState(null, '', url) : window.history.pushState(null, '', url)
+  update(replace ? 'replace' : 'push')
+}
+
+/**
+ * A tab kept in the URL (`?tab=…`), so a refresh or a shared link opens the same
+ * tab. The first value is the default and stays out of the URL.
+ *
+ *   const [tab, setTab] = useTab(['fields', 'settings', 'submissions'])
+ */
+export function useTab<T extends string>(values: readonly T[], key = 'tab'): [T, (value: T) => void] {
+  const { query } = useLocation()
+  const current = values.includes(query[key] as T) ? (query[key] as T) : values[0]
+  return [current, (value: T) => setQuery({ [key]: value === values[0] ? null : value })]
+}
+
+export interface LinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
+  to: string
+}
+
+export function Link({ to, onClick, onMouseEnter, onFocus, ...props }: LinkProps) {
+  const external = /^https?:\/\//.test(to)
+  return createElement('a', {
+    ...props,
+    href: external ? to : boot.base + (to === '/' ? '' : to),
+    onMouseEnter: (event: MouseEvent<HTMLAnchorElement>) => {
+      onMouseEnter?.(event)
+      prefetch(to)
+    },
+    onFocus: (event: FocusEvent<HTMLAnchorElement>) => {
+      onFocus?.(event)
+      prefetch(to)
+    },
+    onClick: (event: MouseEvent<HTMLAnchorElement>) => {
+      onClick?.(event)
+      if (event.defaultPrevented || external || event.metaKey || event.ctrlKey || event.shiftKey || event.button !== 0 || props.target === '_blank') return
+      event.preventDefault()
+      navigate(to)
+    },
+  })
+}

package/src/types.ts

@@ -0,0 +1,337 @@
+import type { ReactNode } from 'react'
+
+export interface SurfaceComponentInfo {
+  id: string
+  label: string
+  description: string
+  props: Record<string, unknown>
+  children: boolean
+}
+
+/** Versioned data, never generated JSX, HTML, CSS or executable code. */
+export interface SurfaceDocument {
+  version: 1
+  id: string
+  title: string
+  spec: { root: string; elements: Record<string, SurfaceElement> }
+}
+
+export interface SurfaceElement {
+  type: string
+  props: Record<string, unknown>
+  children?: string[]
+  on?: Record<string, { action: string; params?: Record<string, unknown> }>
+}
+
+export interface SurfaceAction {
+  node: string
+  name: string
+}
+
+/** Renderers own their interactions; the host sends action identifiers to the server. */
+export interface SurfaceComponentProps<P = Record<string, unknown>> {
+  props: P
+  children?: ReactNode
+  disabled: boolean
+  onAction: (name: string) => void
+}
+
+/** The product's display name, links and images, from brand/brand.json. */
+export interface BrandInfo {
+  name: string
+  domain: string
+  product_url: string
+  docs_url: string
+  github_url: string
+  support_email: string
+  mark: string
+  wordmark: string
+}
+
+export interface Boot {
+  base: string
+  api: string
+  version: string
+  brand: BrandInfo
+  site: { name: string; url: string }
+  /** The name of this site's XSRF cookie. */
+  xsrfCookie?: string
+  /** The admin's language, the languages it speaks (code → name) and its strings in that language. */
+  locale?: string
+  languages?: Record<string, string>
+  messages?: Record<string, string>
+  /** The signed-in user's manifest, sent along with the page so the admin starts without waiting for it. */
+  manifest?: Manifest
+}
+
+export interface FieldDef {
+  handle: string
+  /** Control identity assigned by Fields; nested controls include their value path. */
+  id?: string
+  describedBy?: string
+  type: string
+  label: string
+  instructions?: string
+  required?: boolean
+  default?: unknown
+  width?: 'full' | 'half' | 'third' | 'two-thirds'
+  section?: string
+  /** Render with this admin component instead of the type's own (e.g. a json value with a custom editor). */
+  component?: string
+  /** Presentation options the core components understand: an icon in the input, its size, autofill, monospace, `display` (segmented, checkbox). */
+  icon?: string
+  size?: 'xs' | 'sm' | 'md' | 'lg'
+  placeholder?: string
+  autofocus?: boolean
+  autocomplete?: string
+  inputmode?: 'numeric' | 'text'
+  mono?: boolean
+  display?: string
+  /** text: `blur` saves on blur/Enter instead of on every keystroke. */
+  commit?: 'change' | 'blur'
+  /** select segmented: fill the row. */
+  block?: boolean
+  /** Inline rows: where the value comes from (`own` here, or `inherited`) and how to clear it. */
+  status?: 'own' | 'inherited'
+  reset?: () => void
+  /** select: hand values back as numbers. */
+  numeric?: boolean
+  /** Extra classes for the field's wrapper (e.g. a width in a toolbar). */
+  className?: string
+  [option: string]: unknown
+}
+
+export interface FieldTypeDef {
+  key: string
+  label: string
+  icon: string
+  description: string
+  group: string
+  component: string
+  config: FieldDef[]
+}
+
+export interface CollectionSummary {
+  handle: string
+  title: string
+  singular: string
+  /** The create button's label in the user's language ("New Page", "Nieuw bericht"). */
+  newLabel: string
+  icon: string
+  structure: 'list' | 'tree' | 'dated'
+  defaultView?: 'table' | 'grid' | 'calendar'
+  routable: boolean
+  driver: 'database' | 'files'
+  can: { create: boolean; edit: boolean; publish: boolean; delete: boolean }
+}
+
+export interface NavItem {
+  id: string
+  label: string
+  path: string
+  icon: string
+  /** The section it is listed in: of the sidebar, or of the settings sidebar. */
+  section: string
+  /** A keyboard shortcut that opens it, shown with its label (e.g. `mod+j`). */
+  shortcut?: string | null
+  badge?: string | number | null
+}
+
+/** The main sidebar as arranged for this user: items in sections; hidden ones are under More. `personal` when they pinned their own. */
+export interface Sidebar extends Arrangement {
+  personal: boolean
+}
+
+/** A group of an arranged part of the admin (a sidebar section, a home column): item ids in order. An empty label has no heading. */
+export interface ArrangedSection {
+  id: string
+  label: string
+  items: string[]
+}
+
+/** How the sidebar or the home screen is arranged — by a person (a preference) or as the site's default (the `sidebar` and `dashboard` values of the `admin` settings). */
+export interface Arrangement {
+  sections: ArrangedSection[]
+  hidden: string[]
+}
+
+/** A home-screen widget as registered in PHP (`$admin->widget()`); its component is `registry.widgets.get(id)`. */
+export interface WidgetInfo {
+  id: string
+  label: string
+  description: string
+  icon: string
+  column: 'main' | 'side'
+  /** On everyone's home screen until they rearrange it. */
+  enabled: boolean
+  /** The package it comes from (its label). */
+  source: string
+}
+
+export interface Manifest {
+  /** Trusted components for declarative, contextual admin surfaces. */
+  components?: SurfaceComponentInfo[]
+  cms: { version: string; lockedDown: boolean; debug: boolean }
+  brand: BrandInfo
+  site: { name: string; url: string; locales: string[]; defaultLocale: string; timezone: string }
+  user: User & { grants: string[]; preferences: Record<string, unknown> }
+  collections: CollectionSummary[]
+  globals: ({ handle: string; title: string; icon: string } & RecordTimestamps)[]
+  fieldTypes: FieldTypeDef[]
+  settings: { namespace: string; label: string; icon: string; description: string; package: string | null }[]
+  packages: { active: string[]; pending: Record<string, string> }
+  /** Every screen the user may open: the sidebar's in its order (those under More included), then the settings sidebar's. */
+  nav: NavItem[]
+  sidebar: Sidebar
+  /** The settings sidebar: its sections with the ids of their items. */
+  settingsNav: ArrangedSection[]
+  modules: { id: string; url: string; package: string | null }[]
+  styles: string[]
+  /** Home-screen widgets the user may add: shown in the gallery with their description and the package they come from. */
+  widgets: WidgetInfo[]
+  /** The home screen's columns with the ids of the widgets the user sees. */
+  dashboard: ArrangedSection[]
+  /** The home screen as arranged for this user (hidden = in the gallery); `personal` when they arranged their own. */
+  home?: { layout: Arrangement; personal: boolean; problems?: Record<string, string> }
+  commands: { id: string; label: string; icon: string; group: string; path?: string; ability?: string; input?: Record<string, unknown>; keywords?: string[] }[]
+  /** The language the manifest's labels are in. */
+  locale?: string
+  /** Values modules share with every admin user, by settings namespace (see useConfig). */
+  config?: Record<string, Record<string, unknown>>
+}
+
+/** Standard overview metadata. Unknown or inapplicable dates are null. */
+export interface RecordTimestamps {
+  publishedAt: string | null
+  updatedAt: string | null
+}
+
+export interface User extends RecordTimestamps {
+  id: string
+  name: string
+  email: string
+  avatar: string | null
+  initials: string
+  roles: string[]
+  super: boolean
+  locale: string | null
+  /** `active`, `invited` (made by a plugin, no password yet) or `suspended`. */
+  status: string
+  /** No way into the admin: an account of the public site. */
+  visitor: boolean
+  twoFactor: boolean
+  lastLoginAt: string | null
+  createdAt: string | null
+  /** Profile values for the fields in content/users.yaml. */
+  data: Record<string, any>
+}
+
+export type EntryStatus = 'draft' | 'published'
+export type DisplayStatus = 'draft' | 'published' | 'changed' | 'scheduled'
+
+/** Safe identity used by content, history and people pickers. */
+export interface PersonSummary {
+  id: string
+  name: string
+  initials: string
+  avatar: string | null
+}
+
+export type EntryCapabilities = CollectionSummary['can']
+
+/** Editorial values; publication timing and structure use explicit commands. */
+export interface EntryContent {
+  title: string
+  slug: string
+  data: Record<string, any>
+  authorId: string | null
+}
+
+export interface EntrySummary extends RecordTimestamps {
+  id: string
+  collection: string
+  locale: string
+  title: string
+  slug: string
+  uri: string | null
+  status: EntryStatus
+  displayStatus: DisplayStatus
+  parentId: string | null
+  position: number
+  authorId: string | null
+  author: PersonSummary | null
+  /** Opaque persisted content version for mutation preconditions. */
+  version: string
+}
+
+export interface Entry extends EntrySummary {
+  hasDraft: boolean
+  data: Record<string, any>
+  originId: string | null
+  createdAt: string | null
+  translations?: Record<string, string>
+}
+
+export interface Page<T> {
+  items: T[]
+  total: number
+  page: number
+  perPage?: number
+  pages: number
+}
+
+/** Props every field component receives. */
+export interface FieldProps<T = any> {
+  field: FieldDef
+  value: T
+  onChange: (value: T) => void
+  error?: string
+  disabled?: boolean
+  context: FieldContext
+}
+
+export interface FieldContext {
+  /** Path to the containing group/repeater value; the field handle is appended by Fields. */
+  path?: string[]
+  errors?: Record<string, string>
+  entry?: Entry
+  collection?: string
+  locale?: string
+  /** Current (unsaved) entry title. */
+  title?: string
+  /** All current values of the form (for conditional UIs). */
+  values?: Record<string, any>
+  /** Imported fields from the saved blueprint, when configuring a blueprint. */
+  blueprintFields?: FieldDef[]
+  /** Nesting level when fields are edited inside other fields (blueprint sub-fields). */
+  depth?: number
+}
+
+/** Shared content and mutation capabilities available to entry extensions. */
+export interface EntryPanelProps {
+  /** Complete working snapshot, including editorial metadata, for previews. */
+  content: EntryContent
+  entry: Entry | null
+  collection: { handle: string; title: string; singular: string; body?: string; route?: string; structure?: 'list' | 'tree' | 'dated'; resolvedFields: FieldDef[] }
+  values: Record<string, any>
+  title: string
+  setValue: (handle: string, value: any) => void
+  save: () => Promise<void>
+  reload: () => void | Promise<void>
+  editable: boolean
+  can: EntryCapabilities
+  errors: Record<string, string>
+}
+
+/** One body editor workspace. Selection never changes the content or persistence model. */
+export interface EntryEditorProps extends EntryPanelProps {
+  setTitle: (title: string) => void
+  /** The explicitly configured main-content field. */
+  bodyField: FieldDef
+  /** Additional entry.body panels after the main content. */
+  footer: ReactNode
+  /** Host-owned record details, history and plugin tabs. */
+  sidebar: ReactNode
+  sidebarOpen: boolean
+  setSidebarOpen: (open: boolean) => void
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-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.