@exponential-at/ui 0.0.0-stage → 0.1.0

package/catalog/host.json

@@ -0,0 +1,64 @@
+{
+  "$comment": "VAPP-91: the host API contract, the same on all four platforms (TS src/host/, the Rust core's `host` module, which the Swift and Kotlin painters reach through exponential-ui-ffi). A surface needs exactly these from its host: transport, functions, bindings (optional), extensions, theme, catalog negotiation and policy hooks. Every pure rule here is locked by fixtures/host-*.json, replayed by every renderer's conformance runner (conformance/manifest.json).",
+  "version": 2,
+  "a2uiVersion": "v0.9",
+  "messages": {
+    "$comment": "Server → client. The four A2UI v0.9 messages plus two Exponential UI extensions: `applyTemplate` (a registered declarative package's template becomes create + components + data + binds) and `bindDataModel` (a data model path follows a host `source`). A message is ONE object with `version` (optional, must equal a2uiVersion when present) and exactly one kind key.",
+    "a2ui": ["createSurface", "updateComponents", "updateDataModel", "deleteSurface"],
+    "extensions": ["applyTemplate", "bindDataModel"]
+  },
+  "ops": {
+    "$comment": "What the router (`HostRouter.route`) turns a message into. A platform host performs them in order: create = a new EMPTY surface (replacing one with that id), components = updateComponents on it, data = updateDataModel (no `value` = remove the path), bind = subscribe the path to a source resolver, delete = drop the surface and every subscription, send = a client message back over the transport (errors).",
+    "kinds": ["create", "components", "data", "bind", "delete", "send"]
+  },
+  "clientMessages": {
+    "$comment": "Client → server, A2UI v0.9 client_to_server: `{version, action: {name, surfaceId, sourceComponentId, timestamp, context}}` (+ `payload` when the component adds one, e.g. a Select's value) or `{version, error: {code, surfaceId, message, path?}}`.",
+    "errorCodes": ["VALIDATION_FAILED", "INVALID_MESSAGE", "UNSUPPORTED_CATALOG", "SURFACE_NOT_FOUND", "TEMPLATE_NOT_FOUND", "FUNCTION_NOT_FOUND", "FUNCTION_DENIED", "SOURCE_DENIED", "RENDER_FAILED"]
+  },
+  "functions": {
+    "$comment": "An `on.<event>` action `{functionCall: {call, args}}` (A2UI's key, the only one) runs on the client. The catalog's functions are built in (the basic 14 + the 15 core ones: value functions, `set`; `openUrl` is the one with an effect and goes through the URL policy). Any other name is a namespaced HOST function (`app.toast`; an un-namespaced unknown name is a validation issue) that must be REGISTERED by the host (an action function: side effects, may be async) and passes the policy gate first: decide(policy, name) → allow | ask | deny. `ask` = the host's onFunctionCall hook decides (the Exponential app's consent card). Patterns: an exact name or a prefix ending in `*` (`harness.*`). Order: deny wins, then allow, then ask, then `default`.",
+    "decisions": ["allow", "ask", "deny", "not_found"],
+    "defaultPolicy": { "allow": [], "ask": [], "deny": [], "default": "allow" }
+  },
+  "urls": {
+    "$comment": "EVERY href on every renderer goes through decideUrl(policy, url): openUrl, Link (external or not), markdown links, FileUpload file urls, a host's default opener. The scheme (lower-cased) must be in `schemes` (`[\"https\"]` = https only: drops http, mailto and tel) and, when `hosts` is set, an http(s) url's host must match one (exact or `*.example.com`). Relative urls resolve against `baseUrl` first; without one they are denied. A denied href is never navigated: the link paints as plain text. The defaults keep `mailto` and `tel`: they open the system mail or phone handler with the address visible, run nothing, and are not gated by `hosts`. VAPP-107 (decided by Danny): an http(s) url whose host is PRIVATE (`privateHosts`: localhost and *.localhost, *.local, the IPv4 blocks 0/8, 10/8, 127/8, 169.254/16, 172.16/12, 192.168/16, IPv6 ::, ::1, fe80::/10, fc00::/7 and an IPv4-mapped address of a private IPv4) is DENIED with reason `private` unless the host opts it back in with `allowPrivate` (exact names or addresses, `*.suffix`, or `*` for every private address); a `hosts` allowlist alone does not opt one in. LITERALS only: the policy never resolves a name (a public name that resolves to a private address is the host network's job: egress rules, a filtering resolver). The WHATWG parser normalizes an address before the check (`2130706433`, `0x7f.1`, `::ffff:127.0.0.1`). The Exponential app opts its own origin in only when that origin is private (the localhost dev setup); its cloud origin is public and needs nothing; the web renderers (React and Solid, through the shared web layer) do the same for the document's own host on top of the host's list (a dev server on localhost keeps its same-origin loads).",
+    "defaultSchemes": ["https", "http", "mailto", "tel"],
+    "privateHosts": ["localhost", "*.localhost", "*.local", "0.0.0.0/8", "10.0.0.0/8", "127.0.0.0/8", "169.254.0.0/16", "172.16.0.0/12", "192.168.0.0/16", "::", "::1", "fe80::/10", "fc00::/7", "::ffff:<private IPv4>"],
+    "reasons": ["invalid", "scheme", "host", "private"]
+  },
+  "media": {
+    "$comment": "EVERY src on every renderer (Image, Avatar, Video + poster, Audio, markdown images) goes through mediaRequest(url, {baseUrl, rules, schemes, hosts}) → {url, headers} | null. A relative url resolves against baseUrl; the absolute url must pass decideUrl with `schemes` (default `defaultSchemes`: no `file`, so no local file is ever read unless the host lists it; `[\"https\"]` = https only), `hosts` and `allowPrivate` (VAPP-107: a private, loopback or link-local host is denied unless opted in, like every href; a redirect hop passes the same rules); null = denied, nothing loads. Every rule whose `prefix` the url starts with adds its headers (later rules win per header): how the Exponential app sends auth for /api/attachments. Every image loader enforces `limits`: `maxBytes` (Content-Length up front and the body as it streams), `timeoutMs` (the whole request), `maxPixels` (width × height read from the image header BEFORE decoding); a load over a limit fails like a 404 (the fallback paints). Video/Audio stream through the platform player: the policy applies, the byte limits do not (a poster is an image: they do); a web player cannot send headers, so a request WITH headers goes to the host's `mediaStreamUrl(request)` (a signed or cookie-authed url, re-checked by the policy) and without that hook is fetched whole into a blob url under `limits.maxBytes` and `limits.timeoutMs` for the WHOLE download (VAPP-107: past either it fails like a 404; a long video needs `mediaStreamUrl`).",
+    "ruleKeys": ["prefix", "headers"],
+    "optionKeys": ["baseUrl", "rules", "schemes", "hosts", "allowPrivate"],
+    "defaultSchemes": ["https", "http", "data"],
+    "limits": { "maxBytes": 20971520, "timeoutMs": 30000, "maxPixels": 33554432 }
+  },
+  "sources": {
+    "$comment": "A binding source URI: `<scheme>:<name>[?k=v&…]`, scheme `[a-z][a-z0-9+.-]*` (lower-cased), name non-empty without `?`, params percent-decoded (`+` = space), the last value of a repeated key wins, keys sorted. The host registers one resolver per scheme (the Exponential app: `exp`); subscribe(source, emit) → cancel, every emit writes the value at the bound path.",
+    "pattern": "^([a-zA-Z][a-zA-Z0-9+.-]*):([^?]+)(?:\\?(.*))?$"
+  },
+  "transport": {
+    "$comment": "Adapters every SDK ships: in-memory, A2UI JSONL over a byte stream (one message per line; CRLF and blank lines tolerated; a bad line is an issue, never fatal), SSE (`data:` lines joined per event; an event's data is one message or JSONL; events named other than `message`/`a2ui` are ignored), WebSocket (one message or JSONL per frame), and the A2UI-over-MCP carrier (a tool result's `content[]` resources with one of `mcpMimeTypes`, text = JSONL / a JSON array / one message; or `structuredContent.a2ui` = an array). Actions out over MCP = tools/call `mcpActionTool` with `{message}`.",
+    "mcpMimeTypes": ["application/json+a2ui", "application/a2ui+json"],
+    "mcpActionTool": "a2ui_event",
+    "sseEvents": ["message", "a2ui"]
+  },
+  "negotiation": {
+    "$comment": "supportedCatalogIds = the core, the core lite, the A2UI basic catalog, then every registered extension id in registration order, de-duplicated. clientCapabilities = {\"v0.9\": {supportedCatalogIds}}. A createSurface whose catalogId is not in the list → UNSUPPORTED_CATALOG."
+  },
+  "package": {
+    "$comment": "A declarative app package (VAPP-82): data, never code. {id, name, version, catalogId, templates: {<id>: {components: [flat, one `root`], data?, bindings?: [{path, source}]}}, functions?: [allowed patterns], sources?: [allowed sources], theme?: a theme id or theme JSON, icon?}. Installing one registers its templates with the router (applyTemplate) and turns `functions` into the policy for its surfaces: listed = allow, anything else = deny. VAPP-107: `sources` is the same allowlist for binding sources (`exp:devices`, or a prefix `exp:*`, matched against the URI's scheme:name without its query): unset = any registered scheme; set, a template binding outside it is an install issue and a later bindDataModel on one of the package's surfaces answers SOURCE_DENIED (the data model never follows it).",
+    "required": ["id", "name", "version", "catalogId", "templates"]
+  },
+  "paint": {
+    "$comment": "A component whose painter fails (React: a render error; native: a painter that throws or meets props it cannot paint) paints an empty box in its place, never takes the surface down, and calls the host's `onPaintError({surfaceId, componentId, message})` ONCE per surface + component + message. ExponentialHost.paintError forwards it to the agent as an A2UI error `{code: errorCode, surfaceId, message, path: /components/<componentId>}` and reports it as a host issue with the same code.",
+    "hook": "onPaintError",
+    "errorCode": "RENDER_FAILED"
+  },
+  "surface": {
+    "$comment": "Round 2 (docs/round-2-contract.md §3, §5): what a host hands each surface besides messages. `settings` = the SurfaceSettings keys (src/types.ts): `timeZone` = the IANA zone instants show in (default the platform's). `formatter` = the methods of the host-supplied Formatter that formats every number, currency, percent, date and relative time (TS: intlFormatter(locale, timeZone); Rust: the Formatter trait, default the English fallback at the host's UTC offset per instant; FFI: a foreign Formatter, else the core's). `commands` = what a host may ask of a live surface (catalog/a11y.json `commands`; `scrollToIndex` takes the DATA index). Round 4 (VAPP-103): an unusable theme (an unknown built-in id, a missing or other `$schema`, any theme issue) NEVER fails a host: it paints with the default theme and reports the issues (TS `themeOrDefault` + React `HostPlugin.onThemeIssues`, Rust `themes::theme_or_default`, Swift/Kotlin `ThemeHandle.loadOrDefault`); a server's unusable `createSurface.theme` answers VALIDATION_FAILED at `/createSurface/theme`.",
+    "settings": ["locale", "timeZone", "strings", "mode", "density", "contrast", "theme"],
+    "formatter": ["number", "currency", "percent", "date", "relativeTime", "plural"],
+    "commands": ["focus", "announce", "scrollIntoView", "scrollToIndex"]
+  }
+}

package/catalog/layout.json

@@ -0,0 +1,20 @@
+{
+  "$comment": "Round 2 (docs/round-2-contract.md §7): the layout NUMBERS every painter shares where no theme token decides (px unless noted). `windowThreshold` = items past which List and Table window; `windowOverscan` = items rendered beyond each viewport edge; `resizeStep` = percentage points per arrow key on a Resizable handle; `panelMin` = a panel's min (percent) when unset; `resizeHandleHit` = a handle's hit area across its hairline; `fieldIntrinsicWidth` = the max-content width of a text field (Input, Textarea, NumberField, ChipInput: never the browser's `size` default) — picker triggers (Select, DatePicker, DateRangePicker, TimePicker) size to their content; `mediaIntrinsicWidth` = the max-content width of an Image/Video without a width (its min-content is 0); `mediaAspectRatio` = width/height of an Image without `aspectRatio` or a height (Video: its `aspectRatio` default); `treeGuideColumn` = one TreeGuides gutter column (the recipe's `line` width is the STROKE; round 3: 14, the ×4 app indent, the elbow lands on the parent's lead glyph); `treeGuideRadius` = the elbow's corner radius; `treeGuideBridge` = how far the guide verticals overshoot the row's TOP edge (paint only) so a Section's hairline divider never breaks the line. EXP-1259 (packages/domain-contract/fixtures/feedback-states.json + search-list.json): `pendingDelayMs` = how long a `loading` Button waits before it shows the spinner and its `pendingLabel` (a fast action never flashes; presses are refused at once); `skeletonPulseMs` / `skeletonOpacityLow` / `skeletonOpacityHigh` = the placeholder's ONE opacity pulse (low → high → low, ease-in-out), `skeletonReducedOpacity` = its static opacity under reduce motion; `searchListFade` = the bottom fade over a SearchList (or a searchable submenu) while more rows sit below. Generated into every target; src/layout.ts reads it.",
+  "windowThreshold": 50,
+  "windowOverscan": 5,
+  "resizeStep": 10,
+  "panelMin": 10,
+  "resizeHandleHit": 8,
+  "fieldIntrinsicWidth": 160,
+  "mediaIntrinsicWidth": 320,
+  "mediaAspectRatio": 1.7777778,
+  "treeGuideColumn": 14,
+  "treeGuideRadius": 3,
+  "treeGuideBridge": 1,
+  "pendingDelayMs": 150,
+  "skeletonPulseMs": 1600,
+  "skeletonOpacityLow": 0.45,
+  "skeletonOpacityHigh": 0.9,
+  "skeletonReducedOpacity": 0.6,
+  "searchListFade": 24
+}

package/catalog/limits.json

@@ -0,0 +1,9 @@
+{
+  "$comment": "VAPP-103: the input LIMITS every core enforces (the TS reference, the Rust core and through it Swift, Compose and gpui). An agent's input past a limit is refused with an issue, never worked on. `maxComponents` = nodes the reducer places in one surface's tree, template nodes included (the rest is dropped: `surface: more than N components; the rest is dropped`); a renderer's build holds at most `maxComponents` nodes too: the reduced tree's (after expansion, children and slots) plus, per template ITEM, its template subtree's (nested items charged when they are instantiated); the first item that does not fit and every later one are not rendered, with ONE issue on the template component (the same message). `maxDepth` = nesting levels of the REDUCED tree, after macro expansion (the root and every lifted template = 1, children and slots one level down; a Card, Section or Group macro adds a level; a deeper node is the Unknown placeholder, its subtree dropped: `nesting deeper than N levels`); 48 keeps every tree a core emits (2 JSON levels per node) inside serde_json's default recursion limit of 128, so reduced trees, fixtures and the FFI's JSON round-trip; the Rust core's recursive passes switch to a heap-allocated stack segment when the host thread runs low, so an iOS secondary thread's 512 KB never decides (a 48-level surface lays out on a 128 KB thread, debug build). `maxMessageBytes` = one server message as UTF-8 JSON (host routers refuse it: INVALID_MESSAGE). `maxTemplateItems` = template items one surface instantiates (beyond it the items are not rendered: `template: more than N items; the rest is not rendered`). `maxPointerBytes` / `maxPointerSegments` = a data pointer's length and token count (a longer write is refused). Generated into every target; src/limits.ts reads it.",
+  "maxComponents": 20000,
+  "maxDepth": 48,
+  "maxMessageBytes": 4194304,
+  "maxTemplateItems": 10000,
+  "maxPointerBytes": 1024,
+  "maxPointerSegments": 64
+}

package/catalog/locale.json

@@ -0,0 +1,48 @@
+{
+  "$comment": "Round 1 (docs/round-1-contract.md §4): the LOCALE contract. A surface carries one BCP 47 `locale` (SurfaceSettings.locale, default `en-US`); it drives the basic catalog's formatNumber/formatCurrency/formatDate/pluralize, NumberField's display, the calendar's month and weekday names and the default week start, and the text direction. Platforms format with their own ICU (Intl, Foundation, java.text, icu4x); what must not differ is decided HERE so every renderer agrees: `weekStart` = CLDR supplemental weekData `firstDay` by REGION (0 = Sunday … 6 = Saturday; a region not listed = `default`); a locale without a region takes `likelyRegion[language]` (CLDR likelySubtags: every rtl language and the most spoken ~90; else `default`); `languageAliases` = deprecated codes normalised FIRST (Java/Android still emit `iw`, `ji`, `in`); `rtl` = the languages whose text direction is right-to-left (the surface root gets `direction: rtl` unless the author set one); `rtlMirroredIcons` = the DIRECTIONAL glyphs (icons.json names, semantic and Lucide) a painter MIRRORS under rtl: scaleX(-1) as the OUTERMOST transform of the glyph, after the node's own `transform` (CSS `transform: scaleX(-1) <own>`), so a back arrow, a prev/next or breadcrumb chevron and a submenu indicator point the reading direction; media transport glyphs and everything else are never mirrored. Round 2: formatting goes through a host-supplied Formatter (SurfaceSettings.locale + timeZone; TS = Intl, Rust = a Formatter trait with the `englishFallback` below, FFI = a foreign Formatter). src/locale.ts + src/format.ts are the reference; generated into every target as constants. Append-only.",
+  "default": "en-US",
+  "weekStart": {
+    "default": 1,
+    "regions": {
+      "0": ["AG", "AS", "BD", "BR", "BS", "BT", "BW", "BZ", "CA", "CN", "CO", "DM", "DO", "ET", "GT", "GU", "HK", "HN", "ID", "IL", "IN", "JM", "JP", "KE", "KH", "KR", "LA", "MH", "MM", "MO", "MT", "MX", "MZ", "NI", "NP", "PA", "PE", "PH", "PK", "PR", "PT", "PY", "SA", "SG", "SV", "TH", "TT", "TW", "UM", "US", "VE", "VI", "WS", "YE", "ZA", "ZW"],
+      "5": ["MV"],
+      "6": ["AE", "AF", "BH", "DJ", "DZ", "EG", "IQ", "IR", "JO", "KW", "LY", "OM", "QA", "SD", "SY"]
+    }
+  },
+  "likelyRegion": {
+    "af": "ZA", "am": "ET", "ar": "EG", "az": "AZ", "be": "BY", "bg": "BG", "bn": "BD", "bs": "BA", "ca": "ES", "ckb": "IQ", "cs": "CZ", "cy": "GB",
+    "da": "DK", "de": "DE", "dv": "MV", "el": "GR", "en": "US", "es": "ES", "et": "EE", "eu": "ES", "fa": "IR", "fi": "FI", "fil": "PH", "fr": "FR",
+    "ga": "IE", "gl": "ES", "gu": "IN", "ha": "NG", "he": "IL", "hi": "IN", "hr": "HR", "hu": "HU", "hy": "AM", "id": "ID", "ig": "NG", "is": "IS",
+    "it": "IT", "ja": "JP", "jv": "ID", "ka": "GE", "kk": "KZ", "km": "KH", "kn": "IN", "ko": "KR", "ku": "TR", "ky": "KG", "lo": "LA", "lt": "LT",
+    "lv": "LV", "mk": "MK", "ml": "IN", "mn": "MN", "mr": "IN", "ms": "MY", "mt": "MT", "my": "MM", "nb": "NO", "ne": "NP", "nl": "NL", "nn": "NO",
+    "no": "NO", "or": "IN", "pa": "IN", "pl": "PL", "ps": "AF", "pt": "BR", "ro": "RO", "ru": "RU", "sd": "PK", "si": "LK", "sk": "SK", "sl": "SI",
+    "so": "SO", "sq": "AL", "sr": "RS", "sv": "SE", "sw": "TZ", "ta": "IN", "te": "IN", "th": "TH", "tl": "PH", "tr": "TR", "ug": "CN", "uk": "UA",
+    "ur": "PK", "uz": "UZ", "vi": "VN", "yi": "001", "yo": "NG", "zh": "CN", "zu": "ZA"
+  },
+  "languageAliases": { "in": "id", "iw": "he", "ji": "yi", "jw": "jv", "mo": "ro", "tl": "fil" },
+  "rtl": ["ar", "ckb", "dv", "fa", "he", "ps", "sd", "ug", "ur", "yi"],
+  "rtlMirroredIcons": ["ui-back", "ui-chevron-left", "ui-chevron-right", "ui-arrow-right", "ui-send", "ui-undo", "ui-external-link", "arrow-left", "arrow-right", "chevron-left", "chevron-right", "send", "undo-2", "external-link"],
+  "englishFallback": {
+    "$comment": "Round 2 (docs/round-2-contract.md §3): the data of the ENGLISH fallback Formatter (src/format.ts englishFormatter; the Rust core's fallback reads the same): what a renderer without a platform ICU prints, equal to Intl en-US (ICU 74+) for every case of fixtures/format.json. `currencyPrefix` = the en-US prefix per ISO 4217 code (a code not listed prints `unknownCurrency`: `<CODE>` + U+00A0); `currencyDigits` = the minor digits where they are not 2; `relative` = the numeric:auto phrases of a unit at -1/0/+1 and the unit names (singular, plural); `datePatterns` = the TR35 pattern per `style`, `timePattern` = what `time: true` adds, joined by `dateTimeJoin[style]`. Instants show in the surface zone: the fallback takes the zone as a UTC offset per instant from the host (fixtures: `offsetMinutes`).",
+    "months": ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"],
+    "monthsShort": ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"],
+    "weekdays": ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"],
+    "weekdaysShort": ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"],
+    "dayPeriods": ["AM", "PM"],
+    "currencyPrefix": {
+      "USD": "$", "EUR": "€", "GBP": "£", "JPY": "¥", "CNY": "CN¥", "INR": "₹", "KRW": "₩", "CAD": "CA$", "AUD": "A$", "MXN": "MX$",
+      "BRL": "R$", "ILS": "₪", "NZD": "NZ$", "HKD": "HK$", "TWD": "NT$", "VND": "₫", "PHP": "₱", "XAF": "FCFA\u00a0", "XOF": "F\u202fCFA\u00a0"
+    },
+    "currencyDigits": { "JPY": 0, "KRW": 0, "VND": 0, "CLP": 0, "ISK": 0, "UGX": 0, "PYG": 0, "XAF": 0, "XOF": 0, "BHD": 3, "IQD": 3, "JOD": 3, "KWD": 3, "OMR": 3, "TND": 3 },
+    "relative": {
+      "units": { "second": ["second", "seconds"], "minute": ["minute", "minutes"], "hour": ["hour", "hours"], "day": ["day", "days"], "week": ["week", "weeks"], "month": ["month", "months"], "year": ["year", "years"] },
+      "auto": { "second": { "0": "now" }, "day": { "-1": "yesterday", "1": "tomorrow" }, "week": { "-1": "last week", "1": "next week" }, "month": { "-1": "last month", "1": "next month" }, "year": { "-1": "last year", "1": "next year" } },
+      "past": "{value} {unit} ago",
+      "future": "in {value} {unit}"
+    },
+    "unknownCurrency": "{code}\u00a0",
+    "datePatterns": { "short": "M/d/yy", "medium": "MMM d, y", "long": "MMMM d, y", "full": "EEEE, MMMM d, y" },
+    "timePattern": "h:mm a",
+    "dateTimeJoin": { "short": "{date}, {time}", "medium": "{date}, {time}", "long": "{date} at {time}", "full": "{date} at {time}" }
+  }
+}