@westopp/windo 0.1.0

package/src/preview/registry.ts

@@ -0,0 +1,159 @@
+// Pure helpers for the preview runtime — no DOM, no React. Turn module paths
+// into stable ids, flatten context definitions into serialisable metadata,
+// reshape zod errors for the chrome, and order manifest entries by group.
+
+import type { z } from 'zod'
+import type { WindoContextControlMeta, WindoContextMap, WindoContextMeta, WindoFieldError } from '../types'
+
+/** Derive a stable id from a windo file path: basename minus `.windo.tsx`, kebab-cased. */
+export function idFromPath(path: string): string {
+  const base = path.split(/[\\/]/).pop() ?? path
+  const name = base.replace(/\.windo\.tsx$/, '').replace(/\.windo\.(jsx|ts|js)$/, '')
+  return kebab(name)
+}
+
+function kebab(value: string): string {
+  return value
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/[\s_]+/g, '-')
+    .replace(/[^a-zA-Z0-9-]/g, '')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+    .toLowerCase()
+}
+
+/** Flatten a context map into serialisable metadata for the chrome's Context panel. */
+export function buildContextMeta(contexts: WindoContextMap): WindoContextMeta[] {
+  return Object.keys(contexts).map(name => {
+    const def = contexts[name]
+    const controlMap = def.controls ?? {}
+    const controls: WindoContextControlMeta[] = Object.keys(controlMap).map(key => {
+      const spec = controlMap[key]
+      const meta: WindoContextControlMeta = {
+        key,
+        type: spec.type,
+        default: spec.default,
+      }
+      if (spec.label !== undefined) meta.label = spec.label
+      if (spec.options !== undefined) meta.options = [...spec.options]
+      if (spec.min !== undefined) meta.min = spec.min
+      if (spec.max !== undefined) meta.max = spec.max
+      if (spec.step !== undefined) meta.step = spec.step
+      return meta
+    })
+    const meta: WindoContextMeta = {
+      name,
+      ambient: controls.length > 0,
+      hasProvider: !!def.provider,
+      controls,
+    }
+    if (def.label !== undefined) meta.label = def.label
+    if (def.description !== undefined) meta.description = def.description
+    return meta
+  })
+}
+
+/** Map a zod v4 error's issues into the chrome's per-field error shape. */
+export function flattenZodError(err: z.ZodError): WindoFieldError[] {
+  return err.issues.map(issue => ({
+    path: issue.path.join('.'),
+    message: issue.message,
+  }))
+}
+
+/**
+ * Deep-convert a value to something `postMessage` can structured-clone. Functions
+ * and symbols are dropped; React elements become a `[node]` marker; Date/Map/Set
+ * are reduced to plain JSON forms; cycles are broken. Used on every payload that
+ * crosses the iframe boundary (variant patches, defaults, log args) so a stray
+ * ReactNode or SyntheticEvent can't throw a DataCloneError.
+ */
+export function toCloneable(value: unknown): unknown {
+  return cloneValue(value, new WeakSet())
+}
+
+function cloneValue(value: unknown, seen: WeakSet<object>): unknown {
+  if (value === null) return null
+  const t = typeof value
+  if (t === 'string' || t === 'number' || t === 'boolean') return value
+  if (t === 'bigint') return (value as bigint).toString()
+  if (t === 'function' || t === 'symbol' || t === 'undefined') return undefined
+  const obj = value as { $$typeof?: symbol }
+  if (typeof obj.$$typeof === 'symbol') return '[node]'
+  if (value instanceof Date) return value.toISOString()
+  if (seen.has(value as object)) return undefined
+  seen.add(value as object)
+  if (Array.isArray(value)) return value.map(item => cloneValue(item, seen))
+  if (value instanceof Map) return Array.from(value.entries()).map(([k, v]) => [cloneValue(k, seen), cloneValue(v, seen)])
+  if (value instanceof Set) return Array.from(value.values()).map(v => cloneValue(v, seen))
+  const out: Record<string, unknown> = {}
+  for (const key of Object.keys(value as object)) {
+    const cloned = cloneValue((value as Record<string, unknown>)[key], seen)
+    if (cloned !== undefined) out[key] = cloned
+  }
+  return out
+}
+
+/**
+ * Summarize a single log argument for the console. Events and DOM nodes — the
+ * common things passed to `ctx.logger.log(e)` — collapse to compact markers
+ * instead of dumping a 200kB SyntheticEvent across postMessage. Plain data is
+ * kept (bounded in depth/breadth); functions/symbols are dropped.
+ */
+export function summarizeLogArg(value: unknown): unknown {
+  return summarize(value, 0, new WeakSet())
+}
+
+const MAX_DEPTH = 4
+const MAX_KEYS = 40
+const MAX_ITEMS = 50
+
+function summarize(value: unknown, depth: number, seen: WeakSet<object>): unknown {
+  if (value === null) return null
+  const t = typeof value
+  if (t === 'string') return (value as string).length > 2000 ? `${(value as string).slice(0, 2000)}…` : value
+  if (t === 'number' || t === 'boolean') return value
+  if (t === 'bigint') return `${(value as bigint).toString()}n`
+  if (t === 'function') return '[Function]'
+  if (t === 'symbol' || t === 'undefined') return undefined
+
+  // DOM / React event
+  if (typeof Event !== 'undefined' && value instanceof Event) return `[Event ${value.type}]`
+  const ev = value as { nativeEvent?: unknown; type?: unknown }
+  if (ev.nativeEvent !== undefined && typeof ev.type === 'string') return `[Event ${ev.type}]`
+  // DOM node
+  if (typeof Node !== 'undefined' && value instanceof Node) {
+    const el = value as { tagName?: string; nodeName?: string }
+    return `[<${(el.tagName ?? el.nodeName ?? 'node').toLowerCase()}>]`
+  }
+  if (value instanceof Date) return value.toISOString()
+  if (typeof (value as { $$typeof?: symbol }).$$typeof === 'symbol') return '[ReactElement]'
+
+  if (depth >= MAX_DEPTH) return Array.isArray(value) ? '[Array]' : '[Object]'
+  if (seen.has(value as object)) return '[Circular]'
+  seen.add(value as object)
+
+  if (Array.isArray(value)) {
+    const out = value.slice(0, MAX_ITEMS).map(v => summarize(v, depth + 1, seen))
+    if (value.length > MAX_ITEMS) out.push(`…+${value.length - MAX_ITEMS}`)
+    return out
+  }
+  const keys = Object.keys(value as object).slice(0, MAX_KEYS)
+  const out: Record<string, unknown> = {}
+  for (const key of keys) {
+    const cloned = summarize((value as Record<string, unknown>)[key], depth + 1, seen)
+    if (cloned !== undefined) out[key] = cloned
+  }
+  return out
+}
+
+/** Order entries by their group's position in `groupOrder`, then by title. */
+export function sortEntries<T extends { group: string; title: string }>(entries: T[], groupOrder: string[]): T[] {
+  const rank = new Map(groupOrder.map((slug, i) => [slug, i]))
+  return [...entries].sort((a, b) => {
+    const ra = rank.has(a.group) ? (rank.get(a.group) as number) : groupOrder.length
+    const rb = rank.has(b.group) ? (rank.get(b.group) as number) : groupOrder.length
+    if (ra !== rb) return ra - rb
+    return a.title.localeCompare(b.title)
+  })
+}

package/src/preview/render.tsx

@@ -0,0 +1,90 @@
+// The component tree rendered inside the iframe: resolve default props, merge
+// the editor's JSON over the serialisable subset, compose opted-in providers
+// plus any local provider, and render the component under an error boundary.
+
+import type { ErrorInfo, ReactNode } from 'react'
+import { Component } from 'react'
+import type { WindoContextMap, WindoDefinition, WindoPlacement, WindoRenderContext } from '../types'
+
+interface ErrorBoundaryProps {
+  onError: (message: string, stack?: string) => void
+  children: ReactNode
+}
+
+interface ErrorBoundaryState {
+  failed: boolean
+}
+
+class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  state: ErrorBoundaryState = { failed: false }
+
+  static getDerivedStateFromError(): ErrorBoundaryState {
+    return { failed: true }
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo) {
+    const message = error?.message ?? String(error)
+    const stack = error?.stack ?? info?.componentStack ?? undefined
+    this.props.onError(message, stack)
+  }
+
+  componentDidUpdate(prev: ErrorBoundaryProps) {
+    if (prev.children !== this.props.children && this.state.failed) {
+      this.setState({ failed: false })
+    }
+  }
+
+  render() {
+    if (this.state.failed) return null
+    return this.props.children
+  }
+}
+
+export interface PreviewRootProps {
+  def: WindoDefinition
+  ctx: WindoRenderContext
+  values: unknown
+  contexts: WindoContextMap
+  onError: (message: string, stack?: string) => void
+  /** Fires the windo's pointer-bound actions (`enter`/`exit`/`hover`) as the pointer crosses the stage. */
+  onStage: (phase: 'enter' | 'leave') => void
+}
+
+export function PreviewRoot(props: PreviewRootProps) {
+  const { def, ctx, values, contexts, onError, onStage } = props
+
+  const defaultProps = typeof def.defaultProps === 'function' ? (def.defaultProps as (c: WindoRenderContext) => unknown)(ctx) : def.defaultProps
+  const finalProps = { ...(defaultProps as object), ...((values as object) ?? {}) }
+
+  let tree: ReactNode = def.component(finalProps, ctx)
+
+  if (def.providers) {
+    const Local = def.providers
+    tree = <Local ctx={ctx}>{tree}</Local>
+  }
+
+  const uses = def.uses ?? []
+  for (let i = uses.length - 1; i >= 0; i--) {
+    const name = uses[i]
+    const context = contexts[name]
+    if (!context?.provider) continue
+    const Provider = context.provider
+    const contextValues = ctx.contexts[name]
+    tree = (
+      <Provider values={contextValues} ctx={ctx}>
+        {tree}
+      </Provider>
+    )
+  }
+
+  const placement: WindoPlacement = def.placement ?? 'center'
+  // Placements render flush; the `-padding` suffix opts into frame padding.
+  const padded = placement.endsWith('-padding')
+  const align = padded ? placement.slice(0, -'-padding'.length) : placement
+
+  return (
+    <div className={`windo-placement ${align}${padded ? ' padded' : ''}`} onPointerEnter={() => onStage('enter')} onPointerLeave={() => onStage('leave')}>
+      <ErrorBoundary onError={onError}>{tree}</ErrorBoundary>
+    </div>
+  )
+}

package/src/preview/virtual.d.ts

@@ -0,0 +1,8 @@
+// The Vite plugin synthesises this module at build/dev time: it globs the
+// project's `*.windo.tsx` files into lazy importers and bundles the resolved
+// `windo.config.ts`. The preview entry imports both from here.
+
+declare module 'virtual:windo-registry' {
+  export const modules: Record<string, () => Promise<{ default: import('../types').WindoModule }>>
+  export const config: import('../types').WindoConfig
+}

package/src/protocol.ts

@@ -0,0 +1,59 @@
+// The chrome <-> iframe postMessage contract. The schema itself never crosses
+// the boundary: the iframe walks it into a serialisable descriptor, the chrome
+// sends candidate JSON down, the iframe parses and reports back. Every payload
+// here is plain JSON.
+
+import type { WindoContextMeta, WindoEnvState, WindoFieldError, WindoGroup, WindoLogEntry, WindoManifestEntry, WindoPropDoc, WindoSchemaDescriptor, WindoVariantMeta } from './types'
+
+export const WINDO_MSG = 'windo'
+
+/** chrome -> iframe */
+export type WindoHostMessage =
+  | { source: typeof WINDO_MSG; dir: 'host'; type: 'request-manifest' }
+  | { source: typeof WINDO_MSG; dir: 'host'; type: 'select'; id: string }
+  | { source: typeof WINDO_MSG; dir: 'host'; type: 'set-props'; id: string; json: string }
+  | { source: typeof WINDO_MSG; dir: 'host'; type: 'set-env'; env: WindoEnvState }
+  | { source: typeof WINDO_MSG; dir: 'host'; type: 'invoke-action'; id: string; actionId: string }
+
+/** iframe -> chrome */
+export type WindoPreviewMessage =
+  | { source: typeof WINDO_MSG; dir: 'preview'; type: 'ready' }
+  | {
+      source: typeof WINDO_MSG
+      dir: 'preview'
+      type: 'manifest'
+      title: string
+      entries: WindoManifestEntry[]
+      groups: WindoGroup[]
+      contexts: WindoContextMeta[]
+    }
+  | {
+      source: typeof WINDO_MSG
+      dir: 'preview'
+      type: 'describe'
+      id: string
+      descriptor: WindoSchemaDescriptor
+      props: WindoPropDoc[]
+      variants: WindoVariantMeta[]
+      defaults: unknown
+      code: string | null
+    }
+  | { source: typeof WINDO_MSG; dir: 'preview'; type: 'parse-ok'; id: string }
+  | { source: typeof WINDO_MSG; dir: 'preview'; type: 'parse-error'; id: string; errors: WindoFieldError[] }
+  | { source: typeof WINDO_MSG; dir: 'preview'; type: 'log'; entry: WindoLogEntry }
+  | { source: typeof WINDO_MSG; dir: 'preview'; type: 'state'; id: string; state: Record<string, unknown>; actions: { id: string; disabled: boolean }[] }
+  | { source: typeof WINDO_MSG; dir: 'preview'; type: 'render-error'; id: string; message: string; stack?: string }
+
+export type WindoMessage = WindoHostMessage | WindoPreviewMessage
+
+export function isWindoMessage(data: unknown): data is WindoMessage {
+  return typeof data === 'object' && data !== null && (data as { source?: unknown }).source === WINDO_MSG
+}
+
+export function isHostMessage(msg: WindoMessage): msg is WindoHostMessage {
+  return msg.dir === 'host'
+}
+
+export function isPreviewMessage(msg: WindoMessage): msg is WindoPreviewMessage {
+  return msg.dir === 'preview'
+}

package/src/types.ts

@@ -0,0 +1,319 @@
+// Core type system for windo. Everything — the authoring API, the iframe
+// preview runtime, the chrome UI, and the postMessage protocol — is typed
+// against the contracts in this file.
+
+import type { ComponentType, ReactNode } from 'react'
+import type { z } from 'zod'
+
+/* ------------------------------------------------------------------ *
+ * Primitives
+ * ------------------------------------------------------------------ */
+
+export type WindoStatus = 'stable' | 'beta' | 'deprecated'
+
+export const WINDO_STATUSES: readonly WindoStatus[] = ['stable', 'beta', 'deprecated']
+
+/** Anchor a component within the canvas frame. */
+export type WindoPlacementBase = 'center' | 'fill' | 'top' | 'bottom' | 'left' | 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
+
+/**
+ * Where a component renders inside the canvas frame. Placements render flush by
+ * default; append `-padding` to inset the component from the frame edges
+ * (e.g. `top` sits flush at the top, `top-padding` adds breathing room).
+ */
+export type WindoPlacement = WindoPlacementBase | `${WindoPlacementBase}-padding`
+
+const WINDO_PLACEMENT_BASE: readonly WindoPlacementBase[] = ['center', 'fill', 'top', 'bottom', 'left', 'right', 'top-left', 'top-right', 'bottom-left', 'bottom-right']
+
+export const WINDO_PLACEMENTS: readonly WindoPlacement[] = [...WINDO_PLACEMENT_BASE, ...WINDO_PLACEMENT_BASE.map(p => `${p}-padding` as WindoPlacement)]
+
+/** A configured group. Components reference a group by its `slug`. */
+export interface WindoGroup {
+  name: string
+  slug: string
+  description?: string
+}
+
+/* ------------------------------------------------------------------ *
+ * Context system
+ * ------------------------------------------------------------------ */
+
+export type WindoControlType = 'enum' | 'boolean' | 'string' | 'number'
+
+/** A single ambient control: a value plus the metadata to render its toggle. */
+export interface WindoControlSpec<T = unknown> {
+  type: WindoControlType
+  label?: string
+  default: T
+  options?: readonly string[]
+  min?: number
+  max?: number
+  step?: number
+}
+
+export type WindoControlMap = Record<string, WindoControlSpec>
+
+/** Resolve a control map to the value object it produces. */
+export type WindoControlValues<C extends WindoControlMap> = {
+  [K in keyof C]: C[K] extends WindoControlSpec<infer T> ? T : never
+}
+
+/**
+ * A named context. Two capabilities, either or both:
+ *  - `controls`  → ambient values + UI toggles (free, no opt-in needed)
+ *  - `provider`  → a React wrapper, mounted inside the iframe around components
+ *                  that opt in via `uses`
+ */
+export interface WindoContextDefinition<Values = unknown, Provided = Values> {
+  label?: string
+  description?: string
+  controls?: WindoControlMap
+  provider?: ComponentType<{ children: ReactNode; values: Values; ctx: WindoRenderContext }>
+  /** Derive the value exposed on `ctx.contexts[name]`. Defaults to the control values. */
+  resolve?: (values: Values, ctx: WindoRenderContext) => Provided
+}
+
+// Contexts are each generic over a different control map `C`; TS has no existential
+// to hold `exists C. WindoContextDefinition<WindoControlValues<C>>`. `Values` sits in
+// contravariant positions (provider props, resolve arg) so no precise common supertype
+// exists — `any` is the single, contained variance hatch for this heterogeneous
+// registry. Mirrors WindoModule. Definition sites stay precise; this only erases at the
+// point of collection.
+// biome-ignore lint/suspicious/noExplicitAny: existential variance hatch for the heterogeneous context registry
+export type WindoContextMap = Record<string, WindoContextDefinition<any, any>>
+
+/* ------------------------------------------------------------------ *
+ * Render-time context
+ * ------------------------------------------------------------------ */
+
+export interface WindoViewport {
+  width: number
+  height: number
+  name: 'mobile' | 'tablet' | 'desktop'
+}
+
+/** Console channel: `ctx.logger.log(…)` posts an entry to the chrome's Console tab. */
+export interface WindoLogger {
+  log: (...args: unknown[]) => void
+}
+
+/** How an action fires. `click` renders a toolbar button; the rest bind to the stage's pointer events. */
+export type WindoActionTrigger = 'click' | 'enter' | 'exit' | 'hover'
+
+export const WINDO_ACTION_TRIGGERS: readonly WindoActionTrigger[] = ['click', 'enter', 'exit', 'hover']
+
+/**
+ * An out-of-band action that drives a component's state. `click` actions render as
+ * toolbar buttons; `enter`/`exit`/`hover` bind to the stage's pointer events. `run`
+ * receives the live ctx and an `active` flag — for `hover` it is `true` on
+ * pointer-enter and `false` on pointer-leave; for the others it is always `true`.
+ */
+export interface WindoAction<State = unknown> {
+  label: string
+  /** Defaults to `click`. */
+  on?: WindoActionTrigger
+  run: (ctx: WindoRenderContext<State>, active: boolean) => void
+  /** Greys out a `click` action's toolbar button. Evaluated against the live state. */
+  disabled?: (ctx: WindoRenderContext<State>) => boolean
+}
+
+/** Live environment handed to every render-time function inside the iframe. */
+export interface WindoRenderContext<State = unknown> {
+  colorScheme: 'light' | 'dark'
+  viewport: WindoViewport
+  reducedMotion: boolean
+  direction: 'ltr' | 'rtl'
+  locale: string
+  logger: WindoLogger
+  /** Current component-local state, typed by the windo's `State` generic. */
+  state: State
+  /** Merge a patch into the component-local state and re-render. */
+  setState: (patch: Partial<State>) => void
+  /** Resolved values of opted-in contexts, keyed by context name. */
+  contexts: Record<string, unknown>
+}
+
+/* ------------------------------------------------------------------ *
+ * Authoring API
+ * ------------------------------------------------------------------ */
+
+/** A variant: a label plus a partial prop patch. Renders in the gallery and is click-to-apply. */
+export interface WindoVariant<Props> {
+  label: string
+  props: Partial<Props>
+}
+
+/** A row in the authored Props documentation table. */
+export interface WindoPropDoc {
+  name: string
+  type: string
+  default?: string
+  desc?: string
+}
+
+export type WindoDefaultProps<Props, State = unknown> = Props | ((ctx: WindoRenderContext<State>) => Props)
+
+/**
+ * The object returned by a `windo(...)` factory.
+ *
+ * Keystone rule: the surrounding factory runs ONCE (definition-time) for static
+ * fields (title, group, schema). Every function field below — `defaultProps`,
+ * `actions`, `providers`, `component` — runs at render-time with the live `ctx`.
+ * Never close over live values in the static factory body.
+ */
+export interface WindoDefinition<Props = unknown, State = unknown, GroupSlug extends string = string> {
+  title: string
+  group: GroupSlug
+  status?: WindoStatus
+  description?: string
+  deprecation?: string
+  placement?: WindoPlacement
+  /** Initial component-local state. Its shape is the `State` generic; `ctx.state`/`ctx.setState` derive from it. */
+  state?: State
+  /** Out-of-band actions that drive state: toolbar buttons (`click`) and stage pointer triggers (`enter`/`exit`/`hover`). */
+  actions?: WindoAction<State>[]
+  /** zod schema: validator + parser for the JSON-editable prop subset. `z.output ⊆ Props`. */
+  configurableProps?: z.ZodType
+  /** Full props incl. functions/JSX. The editor's JSON overrides merge on top. */
+  defaultProps: WindoDefaultProps<Props, State>
+  /** Names of provider contexts this component opts into. */
+  uses?: string[]
+  variants?: WindoVariant<Props>[]
+  /** Authored documentation table (not derived from the schema). */
+  props?: WindoPropDoc[]
+  /** Optional authored code snippet for the Code tab. */
+  code?: (values: Props) => string
+  /** A local provider wrapping just this windo (in addition to `uses`). */
+  providers?: ComponentType<{ children: ReactNode; ctx: WindoRenderContext<State> }>
+  component: (props: Props, ctx: WindoRenderContext<State>) => ReactNode
+}
+
+/** Argument handed to the `windo(w => ...)` factory. */
+export interface WindoFactoryArg<Groups extends readonly WindoGroup[], Contexts extends WindoContextMap> {
+  /** Configured groups keyed by slug. */
+  groups: Record<Groups[number]['slug'], WindoGroup>
+  contexts: Contexts
+}
+
+/**
+ * The default export of a `*.windo.tsx` file. A branded, lazily-resolved
+ * definition — the runtime calls `resolve(w)` with the config-derived factory arg.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: variance escape hatch for the heterogeneous WindoModule registry
+export interface WindoModule<Props = any, State = any> {
+  readonly __windo: true
+  resolve: (w: WindoFactoryArg<readonly WindoGroup[], WindoContextMap>) => WindoDefinition<Props, State>
+}
+
+/* ------------------------------------------------------------------ *
+ * Config
+ * ------------------------------------------------------------------ */
+
+export interface WindoConfig<Groups extends readonly WindoGroup[] = readonly WindoGroup[], Contexts extends WindoContextMap = WindoContextMap> {
+  /** Configured groups. A component's `group` must be one of these slugs. */
+  groups: Groups
+  /** Named contexts available to components. */
+  contexts?: Contexts
+  /** Glob(s) for discovery, relative to project root. Default `**\/*.windo.tsx`. */
+  include?: string | string[]
+  /** Title shown in the workbench chrome. */
+  title?: string
+}
+
+/* ------------------------------------------------------------------ *
+ * Schema descriptor (crosses the iframe boundary; renders the controls)
+ * ------------------------------------------------------------------ */
+
+export type WindoControlKind = 'string' | 'number' | 'boolean' | 'enum' | 'date' | 'array' | 'object' | 'unknown'
+
+export interface WindoControlDescriptor {
+  key: string
+  kind: WindoControlKind
+  optional: boolean
+  options?: string[]
+  min?: number
+  max?: number
+  description?: string
+}
+
+export interface WindoSchemaDescriptor {
+  fields: WindoControlDescriptor[]
+}
+
+/* ------------------------------------------------------------------ *
+ * Runtime manifest + protocol payloads
+ * ------------------------------------------------------------------ */
+
+/** Serialisable metadata for one action — drives the canvas toolbar. */
+export interface WindoActionMeta {
+  id: string
+  label: string
+  on: WindoActionTrigger
+}
+
+/** Static, serialisable metadata for one windo — drives the sidebar. */
+export interface WindoManifestEntry {
+  id: string
+  title: string
+  group: string
+  status: WindoStatus
+  description?: string
+  deprecation?: string
+  placement: WindoPlacement
+  uses: string[]
+  hasVariants: boolean
+  actions: WindoActionMeta[]
+  hasState: boolean
+}
+
+export interface WindoVariantMeta {
+  label: string
+  props: Record<string, unknown>
+}
+
+/** Ambient environment pushed from the chrome down into the iframe. */
+export interface WindoEnvState {
+  colorScheme: 'light' | 'dark'
+  viewport: WindoViewport
+  reducedMotion: boolean
+  direction: 'ltr' | 'rtl'
+  locale: string
+  /** Per-context control values, keyed by context name then control key. */
+  contexts: Record<string, Record<string, unknown>>
+}
+
+export interface WindoLogEntry {
+  ts: number
+  args: unknown[]
+}
+
+export interface WindoFieldError {
+  path: string
+  message: string
+}
+
+/* ------------------------------------------------------------------ *
+ * Context metadata (serialisable; drives the chrome's Context panel)
+ * ------------------------------------------------------------------ */
+
+export interface WindoContextControlMeta {
+  key: string
+  type: WindoControlType
+  label?: string
+  options?: string[]
+  default: unknown
+  min?: number
+  max?: number
+  step?: number
+}
+
+export interface WindoContextMeta {
+  name: string
+  label?: string
+  description?: string
+  /** True when the context contributes controls (ambient values). */
+  ambient: boolean
+  /** True when the context mounts a provider (opt-in via `uses`). */
+  hasProvider: boolean
+  controls: WindoContextControlMeta[]
+}