@prestack/thread-ui 0.0.1 → 0.1.0

package/dist/ui/icons.ts

@@ -0,0 +1,331 @@
+import type { Threaded } from '@prestack/thread/core/thread'
+
+export interface IconSet {
+  readonly name: string
+  readonly module: string
+
+  readonly size: number
+
+  readonly nativeStroke?: number
+
+  readonly viewBox: number
+}
+
+const SETS: Readonly<Record<string, IconSet>> = {
+  lucide: { name: 'lucide', module: 'lucide-react', size: 24, nativeStroke: 2, viewBox: 24 },
+  phosphor: { name: 'phosphor', module: '@phosphor-icons/react', size: 24, nativeStroke: 1.5, viewBox: 256 },
+  tabler: { name: 'tabler', module: '@tabler/icons-react', size: 24, nativeStroke: 2, viewBox: 24 },
+  heroicons: { name: 'heroicons', module: '@heroicons/react/24/outline', size: 24, nativeStroke: 1.5, viewBox: 24 },
+  feather: { name: 'feather', module: 'react-icons/fi', size: 24, nativeStroke: 2, viewBox: 24 },
+  remix: { name: 'remix', module: 'react-icons/ri', size: 24, viewBox: 24 },
+  bootstrap: { name: 'bootstrap', module: 'react-icons/bs', size: 16, viewBox: 16 },
+  material: { name: 'material', module: 'react-icons/md', size: 24, viewBox: 24 },
+  ionicons: { name: 'ionicons', module: 'react-icons/io5', size: 24, viewBox: 512 },
+}
+
+export const ICON_TARGET = { size: 24, normalizedStroke: 1.75 } as const
+
+export const DEFAULT_ICON = 'md'
+
+export function sizeRows(rows: readonly { readonly id: string; readonly is?: string }[]): readonly {
+  readonly id: string
+  readonly is: string
+}[] {
+  return rows
+    .filter((row): row is { id: string; is: string } => row.id !== SET_ROW && typeof row.is === 'string')
+    .map((row) => ({ id: row.id, is: row.is }))
+}
+
+export function sizeNamed(name: string): string {
+  return name.startsWith(SIZE_PREFIX) ? name : `${SIZE_PREFIX}${name}`
+}
+
+export function strokeFor(
+
+  set: { readonly viewBox: number; readonly nativeStroke?: number },
+  target: number = ICON_TARGET.normalizedStroke,
+): number | undefined {
+  if (set.nativeStroke === undefined) return undefined
+  return Number(((target * set.viewBox) / ICON_TARGET.size).toFixed(3))
+}
+
+export const BRAND_MODULE = 'simple-icons'
+
+const DRAWN: Readonly<Record<string, Readonly<Record<string, string>>>> = {
+
+  bell: { lucide: 'Bell' },
+  star: { lucide: 'Star' },
+  heart: { lucide: 'Heart' },
+  share: { lucide: 'Share2' },
+  bookmark: { lucide: 'Bookmark' },
+  send: { lucide: 'Send' },
+  attach: { lucide: 'Paperclip' },
+  play: { lucide: 'Play' },
+  pause: { lucide: 'Pause' },
+  chevronLeft: { lucide: 'ChevronLeft' },
+  chevronUp: { lucide: 'ChevronUp' },
+  arrowUp: { lucide: 'ArrowUp' },
+  arrowDown: { lucide: 'ArrowDown' },
+  list: { lucide: 'List' },
+  signOut: { lucide: 'LogOut' },
+  signIn: { lucide: 'LogIn' },
+  secure: { lucide: 'ShieldCheck' },
+  card: { lucide: 'CreditCard' },
+  place: { lucide: 'MapPin' },
+  phone: { lucide: 'Phone' },
+  globe: { lucide: 'Globe' },
+  unlock: { lucide: 'Unlock' },
+  warning: { lucide: 'CircleAlert' },
+  success: { lucide: 'CircleCheck' },
+  failure: { lucide: 'CircleX' },
+  help: { lucide: 'CircleHelp' },
+  save: { lucide: 'Save' },
+  undo: { lucide: 'Undo2' },
+  redo: { lucide: 'Redo2' },
+  zoomIn: { lucide: 'ZoomIn' },
+  zoomOut: { lucide: 'ZoomOut' },
+  folder: { lucide: 'Folder' },
+  document: { lucide: 'FileText' },
+  people: { lucide: 'Users' },
+  addPerson: { lucide: 'UserPlus' },
+  tag: { lucide: 'Tag' },
+  flag: { lucide: 'Flag' },
+  archive: { lucide: 'Archive' },
+  inbox: { lucide: 'Inbox' },
+  light: { lucide: 'Sun' },
+  dark: { lucide: 'Moon' },
+  sound: { lucide: 'Volume2' },
+  mute: { lucide: 'VolumeX' },
+  microphone: { lucide: 'Mic' },
+  camera: { lucide: 'Camera' },
+
+  close: { lucide: 'X', phosphor: 'X', tabler: 'IconX', heroicons: 'XMarkIcon', feather: 'FiX', remix: 'RiCloseLine', bootstrap: 'BsX', material: 'MdClose', ionicons: 'IoClose' },
+  search: { lucide: 'Search', phosphor: 'MagnifyingGlass', tabler: 'IconSearch', heroicons: 'MagnifyingGlassIcon', feather: 'FiSearch', remix: 'RiSearchLine', bootstrap: 'BsSearch', material: 'MdSearch', ionicons: 'IoSearch' },
+  check: { lucide: 'Check', phosphor: 'Check', tabler: 'IconCheck', heroicons: 'CheckIcon', feather: 'FiCheck', remix: 'RiCheckLine', bootstrap: 'BsCheck', material: 'MdCheck', ionicons: 'IoCheckmark' },
+  chevronDown: { lucide: 'ChevronDown', phosphor: 'CaretDown', tabler: 'IconChevronDown', heroicons: 'ChevronDownIcon', feather: 'FiChevronDown', remix: 'RiArrowDownSLine', bootstrap: 'BsChevronDown', material: 'MdKeyboardArrowDown', ionicons: 'IoChevronDown' },
+  chevronRight: { lucide: 'ChevronRight', phosphor: 'CaretRight', tabler: 'IconChevronRight', heroicons: 'ChevronRightIcon', feather: 'FiChevronRight', remix: 'RiArrowRightSLine', bootstrap: 'BsChevronRight', material: 'MdKeyboardArrowRight', ionicons: 'IoChevronForward' },
+  plus: { lucide: 'Plus', phosphor: 'Plus', tabler: 'IconPlus', heroicons: 'PlusIcon', feather: 'FiPlus', remix: 'RiAddLine', bootstrap: 'BsPlus', material: 'MdAdd', ionicons: 'IoAdd' },
+  minus: { lucide: 'Minus', phosphor: 'Minus', tabler: 'IconMinus', heroicons: 'MinusIcon', feather: 'FiMinus', remix: 'RiSubtractLine', bootstrap: 'BsDash', material: 'MdRemove', ionicons: 'IoRemove' },
+  menu: { lucide: 'Menu', phosphor: 'List', tabler: 'IconMenu2', heroicons: 'Bars3Icon', feather: 'FiMenu', remix: 'RiMenuLine', bootstrap: 'BsList', material: 'MdMenu', ionicons: 'IoMenu' },
+  more: { lucide: 'MoreHorizontal', phosphor: 'DotsThree', tabler: 'IconDots', heroicons: 'EllipsisHorizontalIcon', feather: 'FiMoreHorizontal', remix: 'RiMoreLine', bootstrap: 'BsThreeDots', material: 'MdMoreHoriz', ionicons: 'IoEllipsisHorizontal' },
+  user: { lucide: 'User', phosphor: 'User', tabler: 'IconUser', heroicons: 'UserIcon', feather: 'FiUser', remix: 'RiUserLine', bootstrap: 'BsPerson', material: 'MdPerson', ionicons: 'IoPerson' },
+  settings: { lucide: 'Settings', phosphor: 'Gear', tabler: 'IconSettings', heroicons: 'Cog6ToothIcon', feather: 'FiSettings', remix: 'RiSettingsLine', bootstrap: 'BsGear', material: 'MdSettings', ionicons: 'IoSettings' },
+  trash: { lucide: 'Trash2', phosphor: 'Trash', tabler: 'IconTrash', heroicons: 'TrashIcon', feather: 'FiTrash2', remix: 'RiDeleteBinLine', bootstrap: 'BsTrash', material: 'MdDelete', ionicons: 'IoTrash' },
+  edit: { lucide: 'Pencil', phosphor: 'PencilSimple', tabler: 'IconPencil', heroicons: 'PencilIcon', feather: 'FiEdit2', remix: 'RiPencilLine', bootstrap: 'BsPencil', material: 'MdEdit', ionicons: 'IoPencil' },
+  calendar: { lucide: 'Calendar', phosphor: 'Calendar', tabler: 'IconCalendar', heroicons: 'CalendarIcon', feather: 'FiCalendar', remix: 'RiCalendarLine', bootstrap: 'BsCalendar', material: 'MdCalendarToday', ionicons: 'IoCalendar' },
+  clock: { lucide: 'Clock', phosphor: 'Clock', tabler: 'IconClock', heroicons: 'ClockIcon', feather: 'FiClock', remix: 'RiTimeLine', bootstrap: 'BsClock', material: 'MdAccessTime', ionicons: 'IoTime' },
+  eye: { lucide: 'Eye', phosphor: 'Eye', tabler: 'IconEye', heroicons: 'EyeIcon', feather: 'FiEye', remix: 'RiEyeLine', bootstrap: 'BsEye', material: 'MdVisibility', ionicons: 'IoEye' },
+  eyeOff: { lucide: 'EyeOff', phosphor: 'EyeSlash', tabler: 'IconEyeOff', heroicons: 'EyeSlashIcon', feather: 'FiEyeOff', remix: 'RiEyeOffLine', bootstrap: 'BsEyeSlash', material: 'MdVisibilityOff', ionicons: 'IoEyeOff' },
+  alert: { lucide: 'TriangleAlert', phosphor: 'Warning', tabler: 'IconAlertTriangle', heroicons: 'ExclamationTriangleIcon', feather: 'FiAlertTriangle', remix: 'RiErrorWarningLine', bootstrap: 'BsExclamationTriangle', material: 'MdWarning', ionicons: 'IoWarning' },
+  info: { lucide: 'Info', phosphor: 'Info', tabler: 'IconInfoCircle', heroicons: 'InformationCircleIcon', feather: 'FiInfo', remix: 'RiInformationLine', bootstrap: 'BsInfoCircle', material: 'MdInfo', ionicons: 'IoInformationCircle' },
+  externalLink: { lucide: 'ExternalLink', phosphor: 'ArrowSquareOut', tabler: 'IconExternalLink', heroicons: 'ArrowTopRightOnSquareIcon', feather: 'FiExternalLink', remix: 'RiExternalLinkLine', bootstrap: 'BsBoxArrowUpRight', material: 'MdOpenInNew', ionicons: 'IoOpenOutline' },
+  copy: { lucide: 'Copy', phosphor: 'Copy', tabler: 'IconCopy', heroicons: 'DocumentDuplicateIcon', feather: 'FiCopy', remix: 'RiFileCopyLine', bootstrap: 'BsClipboard', material: 'MdContentCopy', ionicons: 'IoCopy' },
+  download: { lucide: 'Download', phosphor: 'DownloadSimple', tabler: 'IconDownload', heroicons: 'ArrowDownTrayIcon', feather: 'FiDownload', remix: 'RiDownloadLine', bootstrap: 'BsDownload', material: 'MdDownload', ionicons: 'IoDownload' },
+  upload: { lucide: 'Upload', phosphor: 'UploadSimple', tabler: 'IconUpload', heroicons: 'ArrowUpTrayIcon', feather: 'FiUpload', remix: 'RiUploadLine', bootstrap: 'BsUpload', material: 'MdUpload', ionicons: 'IoCloudUpload' },
+  filter: { lucide: 'Filter', phosphor: 'Funnel', tabler: 'IconFilter', heroicons: 'FunnelIcon', feather: 'FiFilter', remix: 'RiFilterLine', bootstrap: 'BsFunnel', material: 'MdFilterList', ionicons: 'IoFilter' },
+  home: { lucide: 'House', phosphor: 'House', tabler: 'IconHome', heroicons: 'HomeIcon', feather: 'FiHome', remix: 'RiHomeLine', bootstrap: 'BsHouse', material: 'MdHome', ionicons: 'IoHome' },
+  mail: { lucide: 'Mail', phosphor: 'Envelope', tabler: 'IconMail', heroicons: 'EnvelopeIcon', feather: 'FiMail', remix: 'RiMailLine', bootstrap: 'BsEnvelope', material: 'MdMail', ionicons: 'IoMail' },
+  lock: { lucide: 'Lock', phosphor: 'Lock', tabler: 'IconLock', heroicons: 'LockClosedIcon', feather: 'FiLock', remix: 'RiLockLine', bootstrap: 'BsLock', material: 'MdLock', ionicons: 'IoLockClosed' },
+  refresh: { lucide: 'RefreshCw', phosphor: 'ArrowsClockwise', tabler: 'IconRefresh', heroicons: 'ArrowPathIcon', feather: 'FiRefreshCw', remix: 'RiRefreshLine', bootstrap: 'BsArrowRepeat', material: 'MdRefresh', ionicons: 'IoRefresh' },
+  arrowLeft: { lucide: 'ArrowLeft', phosphor: 'ArrowLeft', tabler: 'IconArrowLeft', heroicons: 'ArrowLeftIcon', feather: 'FiArrowLeft', remix: 'RiArrowLeftLine', bootstrap: 'BsArrowLeft', material: 'MdArrowBack', ionicons: 'IoArrowBack' },
+  arrowRight: { lucide: 'ArrowRight', phosphor: 'ArrowRight', tabler: 'IconArrowRight', heroicons: 'ArrowRightIcon', feather: 'FiArrowRight', remix: 'RiArrowRightLine', bootstrap: 'BsArrowRight', material: 'MdArrowForward', ionicons: 'IoArrowForward' },
+}
+
+const REGISTRY = new Map<string, Readonly<Record<string, string>>>(Object.entries(DRAWN))
+const SET_REGISTRY = new Map<string, IconSet>(Object.entries(SETS))
+
+export function defineIconSet(set: IconSet): void {
+  if (SET_REGISTRY.has(set.name)) throw new Error(`icon set "${set.name}" is already registered`)
+  SET_REGISTRY.set(set.name, set)
+}
+
+export function defineIcon(semantic: string, names: Readonly<Record<string, string>>): void {
+  REGISTRY.set(semantic, { ...REGISTRY.get(semantic), ...names })
+}
+
+export function iconSets(): readonly IconSet[] {
+  return [...SET_REGISTRY.values()].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+}
+
+export function iconSet(name: string): IconSet | undefined {
+  return SET_REGISTRY.get(name)
+}
+
+export function iconNames(): readonly string[] {
+  return [...REGISTRY.keys()].sort()
+}
+
+export function iconIn(set: string, semantic: string): string | undefined {
+  return REGISTRY.get(semantic)?.[set]
+}
+
+export function brandExport(brand: string): string {
+  return `si${brand.charAt(0).toUpperCase()}${brand.slice(1)}`
+}
+
+type Row = Omit<Threaded, 'at'> & {
+  readonly section?: string
+  readonly is?: string
+  readonly sets?: Readonly<Record<string, string>>
+}
+
+const GROUPED: Readonly<Record<string, readonly string[]>> = {
+  navigation: ['chevronUp', 'chevronDown', 'chevronLeft', 'chevronRight', 'arrowUp', 'arrowDown', 'arrowLeft', 'arrowRight', 'home', 'menu', 'more', 'externalLink', 'list'],
+  action: ['close', 'check', 'plus', 'minus', 'search', 'filter', 'edit', 'trash', 'save', 'undo', 'redo', 'copy', 'download', 'upload', 'share', 'send', 'attach', 'refresh', 'archive', 'zoomIn', 'zoomOut'],
+  status: ['alert', 'info', 'warning', 'success', 'failure', 'help', 'bell', 'flag', 'tag'],
+  account: ['user', 'people', 'addPerson', 'signIn', 'signOut', 'settings', 'lock', 'unlock', 'secure', 'eye', 'eyeOff'],
+  content: ['document', 'folder', 'inbox', 'mail', 'calendar', 'clock', 'bookmark', 'star', 'heart', 'card', 'place', 'phone', 'globe'],
+  media: ['play', 'pause', 'sound', 'mute', 'microphone', 'camera', 'light', 'dark'],
+}
+
+const sectionOf = (id: string): string => {
+  for (const [name, held] of Object.entries(GROUPED)) if (held.includes(id)) return name
+  return 'other'
+}
+
+export const SET_ROW = 'library'
+
+export const SIZE_PREFIX = 'icon-'
+
+export const holds: readonly Row[] = [
+  {
+    id: SET_ROW,
+    section: 'the library',
+    is: 'lucide',
+    describes:
+      'Which library every icon is drawn from. One name, because a set answers for the whole app — swapping it redraws every icon at once, and an icon a set does not carry is refused rather than quietly missing.',
+    version: 1,
+  },
+  {
+    id: `${SIZE_PREFIX}sm`,
+    section: 'size',
+    is: '16px',
+    describes:
+      'A symbol drawn inside a line of text, at the size that sits on the same baseline as the words around it.',
+    version: 1,
+  },
+  {
+    id: `${SIZE_PREFIX}md`,
+    section: 'size',
+    is: '24px',
+    describes:
+      'A symbol beside wording, at the size most controls use. What anything asking for an icon is drawn at unless it says otherwise.',
+    version: 1,
+  },
+  {
+    id: `${SIZE_PREFIX}lg`,
+    section: 'size',
+    is: '32px',
+    describes:
+      'A symbol standing on its own, where the drawing is the content rather than a marker beside it.',
+    version: 1,
+  },
+
+  ...Object.keys(DRAWN)
+    .sort((one, two) => {
+      const group = sectionOf(one) < sectionOf(two) ? -1 : sectionOf(one) > sectionOf(two) ? 1 : 0
+      return group !== 0 ? group : one < two ? -1 : one > two ? 1 : 0
+    })
+    .map((semantic): Row => ({
+      id: semantic,
+      section: sectionOf(semantic),
+      sets: DRAWN[semantic] ?? {},
+      describes: `The \`${semantic}\` icon, and what it is called in each library — so wording asks for the meaning and the set decides the drawing.`,
+      version: 1,
+    })),
+]
+
+export const ICONS = {
+  id: 'icon',
+  at: 'thread/ui/icons.ts',
+  describes:
+    'Every icon an app may draw and which library it is drawn from. A row is a meaning — close, search, the chevron that opens a thing — and holds what that meaning is called in each library, so an element asks for the meaning and never for a library’s own name for it. One row says which library answers, and changing it redraws the whole app. An icon nothing declares is refused rather than rendered as a gap, and an app adds its own rows to this same list.',
+  version: 1,
+  cites: [
+    {
+      on: '2026-08-28',
+      said: 'Same for icons. We define icons available in icons.ts AND we make UI read from there and icons.ts pick what icon from what library.',
+    },
+  ],
+  holds,
+} satisfies Threaded & { readonly holds: readonly Row[] }
+
+export function drawnAs(set: string, semantic: string, by: string): string {
+  const held = REGISTRY.get(semantic)
+  if (held === undefined) {
+    const has = [...REGISTRY.keys()].sort().map((one) => `\`${one}\``)
+    throw new Error(
+      `\`${by}\` asks for the \`${semantic}\` icon, and no row declares one by that name. ` +
+        `The declared icons are ${has.join(', ')}. Add a row for it, or name one that exists.`,
+    )
+  }
+  const drawn = held[set]
+  if (drawn !== undefined) return drawn
+  const has = Object.keys(held).sort().map((one) => `\`${one}\``)
+  throw new Error(
+    `\`${by}\` asks for the \`${semantic}\` icon and the app draws from \`${set}\`, which does not carry it. ` +
+      `It is carried by ${has.join(', ')}. Add \`${set}\` to that row, or draw from a library that has it.`,
+  )
+}
+
+export function setNamed(name: string): IconSet {
+  const found = SET_REGISTRY.get(name)
+  if (found !== undefined) return found
+  const has = [...SET_REGISTRY.keys()].sort().map((one) => `\`${one}\``)
+  throw new Error(
+    `\`${name}\` is named as the icon library, and no set by that name is registered. ` +
+      `The registered libraries are ${has.join(', ')}.`,
+  )
+}
+
+export type IconComponent = (props: {
+  readonly size?: number
+  readonly strokeWidth?: number
+  readonly className?: string
+  readonly 'aria-hidden'?: boolean
+  readonly 'aria-label'?: string
+  readonly role?: string
+}) => unknown
+
+let installed:
+  | {
+      readonly set: IconSet
+      readonly drawn: Readonly<Record<string, IconComponent>>
+      readonly sizes?: Readonly<Record<string, string>>
+    }
+  | undefined
+
+export function installIcons(
+  set: IconSet,
+  drawn: Readonly<Record<string, IconComponent>>,
+  sizes?: Readonly<Record<string, string>>,
+): void {
+  installed = { set, drawn, ...(sizes === undefined ? {} : { sizes }) }
+}
+
+export function installedSet(): IconSet | undefined {
+  return installed?.set
+}
+
+export function iconSize(name: string = DEFAULT_ICON): number {
+  const held = installed?.sizes?.[sizeNamed(name)]
+  if (held === undefined) return ICON_TARGET.size
+  const measured = Number.parseFloat(held)
+  return Number.isFinite(measured) ? measured : ICON_TARGET.size
+}
+
+const NOT_INSTALLED =
+  'No icons are installed. The library an app draws from and the symbols it draws are generated ' +
+  'from the icon rows — run `thread icons` and import what it writes, beside the stylesheet. ' +
+  'Without it every icon renders as an empty box, which looks like a missing glyph and is a wiring gap.'
+
+export function drawnFor(semantic: string): IconComponent {
+  if (installed === undefined) throw new Error(NOT_INSTALLED)
+  const component = installed.drawn[semantic]
+  if (component !== undefined) return component
+  const has = Object.keys(installed.drawn).sort().map((one) => `\`${one}\``)
+  throw new Error(
+    `\`${semantic}\` is asked for as an icon, and no row declares one by that name. ` +
+      `The declared icons are ${has.join(', ')}. Add a row for it, or name one that exists.`,
+  )
+}

package/dist/ui/islands/map.ts

@@ -0,0 +1,58 @@
+import { z } from 'zod'
+
+const ElementName = z
+  .string()
+  .regex(/^[A-Z][A-Za-z0-9]*$/, 'must be a component name, e.g. "Card"')
+  .describe('The export name. A screen is reached by importing it, so this is its address.')
+
+export const ViewId = z
+  .string()
+  .regex(/^vw_[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/, 'Expected a view id ("vw_" + snake_case)')
+  .describe('The id of a declared read. A screen names one; it never states what the read does.')
+
+export const ScreenName = ElementName.describe(
+  'The screen’s export name — `Home`, `Pricing`, `SignIn`. What `navigateTo` names, and its whole address.',
+)
+
+export const ScreenSchema = z
+  .strictObject({
+    id: ScreenName,
+    nameKey: z
+      .string()
+      .min(1)
+      .describe('The i18n key naming this screen — in a breadcrumb, a tab, a title. Never prose (rule: every user-facing string is a key).'),
+
+    path: z
+      .string()
+      .regex(/^\/(?:[a-z0-9-]+|\[[a-z][a-zA-Z0-9]*\])(?:\/(?:[a-z0-9-]+|\[[a-z][a-zA-Z0-9]*\]))*$|^\/$/, 'must be an App Router path, e.g. "/campaign/[id]"')
+      .optional()
+      .describe('Where this screen lives. `/`, `/settings`, `/campaign/[id]`. Absent for a sheet, popover, overlay or toast, which a press opens where somebody already is, so it has no address of its own.'),
+
+    entry: z.boolean().default(false).describe('True when somebody can arrive here without following a link from inside the app.'),
+
+    shows: z.array(ViewId).default([]).describe('Declared views this screen binds to. A screen binds; it never fetches.'),
+  })
+  .describe('One screen: where it lives, what it rests on, and whether somebody can arrive at it directly.')
+export type Screen = z.infer<typeof ScreenSchema>
+
+export const LinkSchema = z
+  .strictObject({
+    from: ScreenName.describe('The screen somebody is on.'),
+    to: ScreenName.describe('The screen they arrive at.'),
+    labelKey: z
+      .string()
+      .min(1)
+      .optional()
+      .describe('The i18n key of the button or link somebody presses to get there. Read off the press itself, and absent only when the press carries no wording.'),
+  })
+  .describe('One edge: somebody on `from` can reach `to`.')
+export type Link = z.infer<typeof LinkSchema>
+
+export const MapSchema = z
+  .strictObject({
+    specVersion: z.literal(1),
+    screens: z.array(ScreenSchema).default([]),
+    links: z.array(LinkSchema).default([]),
+  })
+  .describe('The map: the screens an app has and how somebody moves between them.')
+export type MapIsland = z.infer<typeof MapSchema>

package/dist/ui/localizations.ts

@@ -0,0 +1,75 @@
+import type { Threaded } from '@prestack/thread/core/thread'
+
+type Row = Omit<Threaded, 'at'> & {
+  readonly section?: string
+  readonly is?: string
+  readonly sets?: Readonly<Record<string, string>>
+}
+
+export function fileFor(language: string): string {
+  return `i18n/${language}.json`
+}
+
+export const SOURCE_ROW = 'source'
+
+export const holds: readonly Row[] = [
+  {
+    id: SOURCE_ROW,
+    section: 'the source',
+    is: 'en',
+    describes:
+      'Which language this app is written in. One name, and it has to be one of the languages declared below — everything else is a translation of it, and the wording commands ask for those and never for this one twice.',
+    version: 1,
+  },
+]
+
+export const declares: readonly (Row & { readonly at: string })[] = [
+  {
+    id: 'en',
+    at: fileFor('en'),
+    section: 'languages',
+    is: 'English',
+    sets: { flag: '🇬🇧' },
+    describes:
+      'English, and everything this app says in it. Named in its own language, because the list this feeds is read by somebody who cannot yet read the language the app is currently in.',
+    version: 1,
+  },
+]
+
+export const LOCALIZATIONS: Threaded & {
+  readonly files: string
+  readonly holds: readonly Row[]
+  readonly declares: readonly (Row & { readonly at: string })[]
+} = {
+  id: 'localization',
+  at: 'thread/ui/localizations.ts',
+  files: fileFor('*'),
+  describes:
+    'Every language an app is in, and which one it is written in. A row is a language tag, the language’s name in itself and a flag to show beside it, so a settings screen offering a choice is built from declarations rather than from a list somebody keeps in a component. Adding a row is what brings a wording file for that language into existence, and every key the interface names has to be answered in every language declared here — an unanswered one is a build error rather than a word that silently comes out in the wrong language.',
+  version: 1,
+  cites: [
+    {
+      on: '2026-08-29',
+      said: 'i18n ships by default, nothing hardcoded in the UI at all. i18n is REQUIRED. We define the languages the app will have, this generates automatically the i18n files so that we can add the stuff there.',
+    },
+    {
+      on: '2026-08-29',
+      said: 'This means that we need a new Localization.ts file under UI, where we declare the languages the app is in, must be threaded on attach. This might maybe include an emoji for the country flag? And name of the language so we can reuse this in settings later',
+    },
+  ],
+  holds,
+  declares,
+}
+
+export function languagesIn(
+  rows: readonly { readonly id: string; readonly is?: string; readonly sets?: Readonly<Record<string, string>> }[],
+): readonly { readonly id: string; readonly name: string; readonly flag: string }[] {
+  return rows
+    .filter((row) => row.id !== SOURCE_ROW)
+    .map((row) => ({ id: row.id, name: row.is ?? row.id, flag: row.sets?.flag ?? '' }))
+}
+
+export function sourceIn(rows: readonly { readonly id: string; readonly is?: string }[]): string | undefined {
+  return rows.find((row) => row.id === SOURCE_ROW)?.is
+}
+