@westopp/windo 0.1.1 → 0.1.2

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/define-config.ts","../src/descriptor.ts","../src/protocol.ts","../src/types.ts"],"sourcesContent":["// The authoring API. `defineWindoConfig` is the single entry point: it captures\n// the project's groups + contexts and hands back a `windo` factory whose `group`\n// field is type-checked against the configured slugs.\n\nimport type { ComponentType, ReactNode } from 'react'\nimport type { z } from 'zod'\nimport type { WindoConfig, WindoContextDefinition, WindoContextMap, WindoControlMap, WindoControlValues, WindoDefinition, WindoFactoryArg, WindoGroup, WindoModule, WindoRenderContext } from './types'\n\nexport interface DefineWindoConfigResult<Groups extends readonly WindoGroup[], Tags extends readonly string[], Contexts extends WindoContextMap> {\n  config: WindoConfig<Groups, Contexts, Tags>\n  windo: <Props, State = Record<string, never>>(\n    factory: (w: WindoFactoryArg<Groups, Contexts, Tags>) => WindoDefinition<Props, State, Groups[number]['slug'], Tags[number]>\n  ) => WindoModule<Props, State>\n}\n\nexport function defineWindoConfig<const Groups extends readonly WindoGroup[], const Tags extends readonly string[] = readonly [], Contexts extends WindoContextMap = Record<string, never>>(\n  config: WindoConfig<Groups, Contexts, Tags>\n): DefineWindoConfigResult<Groups, Tags, Contexts> {\n  function windo<Props, State = Record<string, never>>(\n    factory: (w: WindoFactoryArg<Groups, Contexts, Tags>) => WindoDefinition<Props, State, Groups[number]['slug'], Tags[number]>\n  ): WindoModule<Props, State> {\n    return {\n      __windo: true,\n      resolve: w => factory(w as unknown as WindoFactoryArg<Groups, Contexts, Tags>),\n    }\n  }\n  return { config, windo }\n}\n\n/**\n * Define a named context. A context can contribute ambient `controls` (values +\n * UI), a `provider` (mounted inside the iframe for components that opt in via\n * `uses`), or both.\n *\n * No cast: `def` is already structurally a `WindoContextDefinition<WindoControlValues<C>,\n * Provided>` (only `controls` widens, covariantly). The unavoidable variance — TS has\n * no existential type to hold contexts heterogeneous in `C` — is absorbed once, in\n * `WindoContextMap`, not here and not at call sites.\n */\nexport function defineContext<C extends WindoControlMap, Provided = WindoControlValues<C>>(def: {\n  label?: string\n  description?: string\n  controls?: C\n  provider?: ComponentType<{ children: ReactNode; values: WindoControlValues<C>; ctx: WindoRenderContext }>\n  resolve?: (values: WindoControlValues<C>, ctx: WindoRenderContext) => Provided\n}): WindoContextDefinition<WindoControlValues<C>, Provided> {\n  return def\n}\n\n/**\n * Bind a zod schema to a component's props. The generic carries the component's\n * prop type so the schema's output stays a subset of it; the returned schema is\n * the runtime validator + parser (`z.input` is the JSON edit surface, `z.output`\n * is what the component receives).\n */\nexport function configurableProps<P>() {\n  return <S extends z.ZodType<Partial<P>>>(schema: S): S => schema\n}\n","// Walk a zod schema into a serialisable descriptor that can cross the iframe\n// boundary and render the Controls/Schema UI. We lean on `z.toJSONSchema` (zod\n// v4) for the input shape (enum options, min/max, optionality), then enrich the\n// kind from the zod node's own type tag — some types (Date, Map, Set) are\n// unrepresentable in JSON Schema and come back as `{}`, but their zod `def.type`\n// is exact. The live schema (with transforms/coerce/refine) stays in the iframe\n// and does the actual parsing — only this descriptor travels.\n\nimport { z } from 'zod'\nimport type { WindoControlDescriptor, WindoControlKind, WindoSchemaDescriptor } from './types'\n\ninterface JsonNode {\n  type?: string | string[]\n  enum?: unknown[]\n  const?: unknown\n  format?: string\n  properties?: Record<string, JsonNode>\n  required?: string[]\n  items?: JsonNode\n  anyOf?: JsonNode[]\n  oneOf?: JsonNode[]\n  allOf?: JsonNode[]\n  minimum?: number\n  maximum?: number\n  description?: string\n}\n\nexport function describeSchema(schema: z.ZodType | undefined | null): WindoSchemaDescriptor {\n  if (!schema) return { fields: [] }\n  let json: JsonNode\n  try {\n    json = z.toJSONSchema(schema, { io: 'input', unrepresentable: 'any' }) as JsonNode\n  } catch {\n    return { fields: [] }\n  }\n  const root = unwrap(json)\n  const properties = root.properties ?? {}\n  const required = new Set(root.required ?? [])\n  const zodKinds = shapeKinds(schema)\n  const fields: WindoControlDescriptor[] = Object.keys(properties).map(key => fieldFrom(key, properties[key], required.has(key), zodKinds[key]))\n  return { fields }\n}\n\n// JSON Schema often wraps the object in anyOf (for optional/nullable). Find the\n// node that actually carries the object's properties.\nfunction unwrap(node: JsonNode): JsonNode {\n  if (node.properties) return node\n  const branches = node.anyOf ?? node.oneOf ?? node.allOf\n  if (branches) {\n    const withProps = branches.find(b => b.properties)\n    if (withProps) return withProps\n  }\n  return node\n}\n\nfunction fieldFrom(key: string, node: JsonNode, isRequired: boolean, zodKind?: WindoControlKind): WindoControlDescriptor {\n  const inner = collapseNullable(node)\n  let kind = kindOf(inner)\n  // The zod tag wins for types JSON Schema can't express (date/array/object that\n  // came back as {}), and as a fallback whenever the JSON kind is unknown.\n  if (zodKind && (kind === 'unknown' || zodKind === 'date')) kind = zodKind\n  const descriptor: WindoControlDescriptor = {\n    key,\n    kind,\n    optional: !isRequired || isNullable(node),\n  }\n  if (inner.description) descriptor.description = inner.description\n  const options = enumOptions(inner)\n  if (options) descriptor.options = options\n  if (typeof inner.minimum === 'number') descriptor.min = inner.minimum\n  if (typeof inner.maximum === 'number') descriptor.max = inner.maximum\n  return descriptor\n}\n\nfunction isNullable(node: JsonNode): boolean {\n  const branches = node.anyOf ?? node.oneOf\n  if (!branches) return false\n  return branches.some(b => b.type === 'null')\n}\n\n// Strip a `{ anyOf: [T, null] }` wrapper down to T.\nfunction collapseNullable(node: JsonNode): JsonNode {\n  const branches = node.anyOf ?? node.oneOf\n  if (!branches) return node\n  const nonNull = branches.filter(b => b.type !== 'null')\n  if (nonNull.length === 1) return nonNull[0]\n  return node\n}\n\nfunction enumOptions(node: JsonNode): string[] | undefined {\n  if (Array.isArray(node.enum)) return node.enum.map(v => String(v))\n  const branches = node.anyOf ?? node.oneOf\n  if (branches?.every(b => b.const !== undefined)) {\n    return branches.map(b => String(b.const))\n  }\n  return undefined\n}\n\nfunction kindOf(node: JsonNode): WindoControlKind {\n  if (Array.isArray(node.enum) || (node.anyOf?.every(b => b.const !== undefined) ?? false)) return 'enum'\n  if (node.format === 'date-time' || node.format === 'date') return 'date'\n  const type = Array.isArray(node.type) ? node.type.find(t => t !== 'null') : node.type\n  switch (type) {\n    case 'string':\n      return 'string'\n    case 'number':\n    case 'integer':\n      return 'number'\n    case 'boolean':\n      return 'boolean'\n    case 'array':\n      return 'array'\n    case 'object':\n      return 'object'\n    default:\n      return 'unknown'\n  }\n}\n\n/* ------------------------------------------------------------------ *\n * zod node introspection (the kind source of truth for unrepresentable types)\n * ------------------------------------------------------------------ */\n\ninterface ZodDefLike {\n  type?: string\n  innerType?: unknown\n}\n\nfunction zodDef(node: unknown): ZodDefLike | undefined {\n  const n = node as { def?: ZodDefLike; _zod?: { def?: ZodDefLike } } | null\n  if (!n || typeof n !== 'object') return undefined\n  return n.def ?? n._zod?.def\n}\n\nconst ZOD_WRAPPERS = new Set(['optional', 'nullable', 'default', 'prefault', 'catch', 'readonly', 'nonoptional', 'lazy'])\n\n// Unwrap optional/nullable/default/... down to the meaningful inner node.\nfunction unwrapZodDef(node: unknown): ZodDefLike | undefined {\n  let def = zodDef(node)\n  let guard = 0\n  while (def && def.innerType && ZOD_WRAPPERS.has(def.type ?? '') && guard++ < 16) {\n    def = zodDef(def.innerType)\n  }\n  return def\n}\n\nfunction mapZodType(type: string | undefined): WindoControlKind | undefined {\n  switch (type) {\n    case 'date':\n      return 'date'\n    case 'string':\n      return 'string'\n    case 'number':\n    case 'int':\n    case 'bigint':\n      return 'number'\n    case 'boolean':\n      return 'boolean'\n    case 'array':\n    case 'set':\n    case 'tuple':\n      return 'array'\n    case 'object':\n    case 'record':\n    case 'map':\n      return 'object'\n    case 'enum':\n    case 'literal':\n      return 'enum'\n    default:\n      return undefined\n  }\n}\n\n// Per-field kind read straight from the zod object's shape.\nfunction shapeKinds(schema: z.ZodType): Record<string, WindoControlKind> {\n  const shape = (schema as { shape?: Record<string, unknown> }).shape\n  if (!shape || typeof shape !== 'object') return {}\n  const out: Record<string, WindoControlKind> = {}\n  for (const key of Object.keys(shape)) {\n    const kind = mapZodType(unwrapZodDef(shape[key])?.type)\n    if (kind) out[key] = kind\n  }\n  return out\n}\n","// The chrome <-> iframe postMessage contract. The schema itself never crosses\n// the boundary: the iframe walks it into a serialisable descriptor, the chrome\n// sends candidate JSON down, the iframe parses and reports back. Every payload\n// here is plain JSON.\n\nimport type { WindoContextMeta, WindoEnvState, WindoFieldError, WindoGroup, WindoLogEntry, WindoManifestEntry, WindoPropDoc, WindoSchemaDescriptor, WindoVariantMeta } from './types'\n\nexport const WINDO_MSG = 'windo'\n\n/** chrome -> iframe */\nexport type WindoHostMessage =\n  | { source: typeof WINDO_MSG; dir: 'host'; type: 'request-manifest' }\n  | { source: typeof WINDO_MSG; dir: 'host'; type: 'select'; id: string }\n  | { source: typeof WINDO_MSG; dir: 'host'; type: 'set-props'; id: string; json: string }\n  | { source: typeof WINDO_MSG; dir: 'host'; type: 'set-env'; env: WindoEnvState }\n  | { source: typeof WINDO_MSG; dir: 'host'; type: 'invoke-action'; id: string; actionId: string }\n\n/** iframe -> chrome */\nexport type WindoPreviewMessage =\n  | { source: typeof WINDO_MSG; dir: 'preview'; type: 'ready' }\n  | {\n      source: typeof WINDO_MSG\n      dir: 'preview'\n      type: 'manifest'\n      title: string\n      entries: WindoManifestEntry[]\n      groups: WindoGroup[]\n      tags: string[]\n      contexts: WindoContextMeta[]\n    }\n  | {\n      source: typeof WINDO_MSG\n      dir: 'preview'\n      type: 'describe'\n      id: string\n      descriptor: WindoSchemaDescriptor\n      props: WindoPropDoc[]\n      variants: WindoVariantMeta[]\n      defaults: unknown\n      code: string | null\n    }\n  | { source: typeof WINDO_MSG; dir: 'preview'; type: 'parse-ok'; id: string }\n  | { source: typeof WINDO_MSG; dir: 'preview'; type: 'parse-error'; id: string; errors: WindoFieldError[] }\n  | { source: typeof WINDO_MSG; dir: 'preview'; type: 'log'; entry: WindoLogEntry }\n  | { source: typeof WINDO_MSG; dir: 'preview'; type: 'state'; id: string; state: Record<string, unknown>; actions: { id: string; disabled: boolean }[] }\n  | { source: typeof WINDO_MSG; dir: 'preview'; type: 'render-error'; id: string; message: string; stack?: string }\n\nexport type WindoMessage = WindoHostMessage | WindoPreviewMessage\n\nexport function isWindoMessage(data: unknown): data is WindoMessage {\n  return typeof data === 'object' && data !== null && (data as { source?: unknown }).source === WINDO_MSG\n}\n\nexport function isHostMessage(msg: WindoMessage): msg is WindoHostMessage {\n  return msg.dir === 'host'\n}\n\nexport function isPreviewMessage(msg: WindoMessage): msg is WindoPreviewMessage {\n  return msg.dir === 'preview'\n}\n","// Core type system for windo. Everything — the authoring API, the iframe\n// preview runtime, the chrome UI, and the postMessage protocol — is typed\n// against the contracts in this file.\n\nimport type { ComponentType, ReactNode } from 'react'\nimport type { z } from 'zod'\n\n/* ------------------------------------------------------------------ *\n * Primitives\n * ------------------------------------------------------------------ */\n\nexport type WindoStatus = 'stable' | 'beta' | 'deprecated'\n\nexport const WINDO_STATUSES: readonly WindoStatus[] = ['stable', 'beta', 'deprecated']\n\n/** Anchor a component within the canvas frame. */\nexport type WindoPlacementBase = 'center' | 'fill' | 'top' | 'bottom' | 'left' | 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'\n\n/**\n * Where a component renders inside the canvas frame. Placements render flush by\n * default; append `-padding` to inset the component from the frame edges\n * (e.g. `top` sits flush at the top, `top-padding` adds breathing room).\n */\nexport type WindoPlacement = WindoPlacementBase | `${WindoPlacementBase}-padding`\n\nconst WINDO_PLACEMENT_BASE: readonly WindoPlacementBase[] = ['center', 'fill', 'top', 'bottom', 'left', 'right', 'top-left', 'top-right', 'bottom-left', 'bottom-right']\n\nexport const WINDO_PLACEMENTS: readonly WindoPlacement[] = [...WINDO_PLACEMENT_BASE, ...WINDO_PLACEMENT_BASE.map(p => `${p}-padding` as WindoPlacement)]\n\n/** A configured group. Components reference a group by its `slug`. */\nexport interface WindoGroup {\n  name: string\n  slug: string\n  description?: string\n}\n\n/* ------------------------------------------------------------------ *\n * Context system\n * ------------------------------------------------------------------ */\n\nexport type WindoControlType = 'enum' | 'boolean' | 'string' | 'number'\n\n/** A single ambient control: a value plus the metadata to render its toggle. */\nexport interface WindoControlSpec<T = unknown> {\n  type: WindoControlType\n  label?: string\n  default: T\n  options?: readonly string[]\n  min?: number\n  max?: number\n  step?: number\n}\n\nexport type WindoControlMap = Record<string, WindoControlSpec>\n\n/** Resolve a control map to the value object it produces. */\nexport type WindoControlValues<C extends WindoControlMap> = {\n  [K in keyof C]: C[K] extends WindoControlSpec<infer T> ? T : never\n}\n\n/**\n * A named context. Two capabilities, either or both:\n *  - `controls`  → ambient values + UI toggles (free, no opt-in needed)\n *  - `provider`  → a React wrapper, mounted inside the iframe around components\n *                  that opt in via `uses`\n */\nexport interface WindoContextDefinition<Values = unknown, Provided = Values> {\n  label?: string\n  description?: string\n  controls?: WindoControlMap\n  provider?: ComponentType<{ children: ReactNode; values: Values; ctx: WindoRenderContext }>\n  /** Derive the value exposed on `ctx.contexts[name]`. Defaults to the control values. */\n  resolve?: (values: Values, ctx: WindoRenderContext) => Provided\n}\n\n// Contexts are each generic over a different control map `C`; TS has no existential\n// to hold `exists C. WindoContextDefinition<WindoControlValues<C>>`. `Values` sits in\n// contravariant positions (provider props, resolve arg) so no precise common supertype\n// exists — `any` is the single, contained variance hatch for this heterogeneous\n// registry. Mirrors WindoModule. Definition sites stay precise; this only erases at the\n// point of collection.\n// biome-ignore lint/suspicious/noExplicitAny: existential variance hatch for the heterogeneous context registry\nexport type WindoContextMap = Record<string, WindoContextDefinition<any, any>>\n\n/* ------------------------------------------------------------------ *\n * Render-time context\n * ------------------------------------------------------------------ */\n\nexport interface WindoViewport {\n  width: number\n  height: number\n  name: 'mobile' | 'tablet' | 'desktop'\n}\n\n/** Console channel: `ctx.logger.log(…)` posts an entry to the chrome's Console tab. */\nexport interface WindoLogger {\n  log: (...args: unknown[]) => void\n}\n\n/** How an action fires. `click` renders a toolbar button; the rest bind to the stage's pointer events. */\nexport type WindoActionTrigger = 'click' | 'enter' | 'exit' | 'hover'\n\nexport const WINDO_ACTION_TRIGGERS: readonly WindoActionTrigger[] = ['click', 'enter', 'exit', 'hover']\n\n/**\n * An out-of-band action that drives a component's state. `click` actions render as\n * toolbar buttons; `enter`/`exit`/`hover` bind to the stage's pointer events. `run`\n * receives the live ctx and an `active` flag — for `hover` it is `true` on\n * pointer-enter and `false` on pointer-leave; for the others it is always `true`.\n */\nexport interface WindoAction<State = unknown> {\n  label: string\n  /** Defaults to `click`. */\n  on?: WindoActionTrigger\n  run: (ctx: WindoRenderContext<State>, active: boolean) => void\n  /** Greys out a `click` action's toolbar button. Evaluated against the live state. */\n  disabled?: (ctx: WindoRenderContext<State>) => boolean\n}\n\n/** Live environment handed to every render-time function inside the iframe. */\nexport interface WindoRenderContext<State = unknown> {\n  colorScheme: 'light' | 'dark'\n  viewport: WindoViewport\n  reducedMotion: boolean\n  direction: 'ltr' | 'rtl'\n  locale: string\n  logger: WindoLogger\n  /** Current component-local state, typed by the windo's `State` generic. */\n  state: State\n  /** Merge a patch into the component-local state and re-render. */\n  setState: (patch: Partial<State>) => void\n  /** Resolved values of opted-in contexts, keyed by context name. */\n  contexts: Record<string, unknown>\n}\n\n/* ------------------------------------------------------------------ *\n * Authoring API\n * ------------------------------------------------------------------ */\n\n/** A variant: a label plus a partial prop patch. Renders in the gallery and is click-to-apply. */\nexport interface WindoVariant<Props> {\n  label: string\n  props: Partial<Props>\n}\n\n/** A row in the authored Props documentation table. */\nexport interface WindoPropDoc {\n  name: string\n  type: string\n  default?: string\n  desc?: string\n}\n\nexport type WindoDefaultProps<Props, State = unknown> = Props | ((ctx: WindoRenderContext<State>) => Props)\n\n/**\n * The object returned by a `windo(...)` factory.\n *\n * Keystone rule: the surrounding factory runs ONCE (definition-time) for static\n * fields (title, group, schema). Every function field below — `defaultProps`,\n * `actions`, `providers`, `component` — runs at render-time with the live `ctx`.\n * Never close over live values in the static factory body.\n */\nexport interface WindoDefinition<Props = unknown, State = unknown, GroupSlug extends string = string, Tag extends string = string> {\n  title: string\n  group: GroupSlug\n  /** Tags this component carries. Each must be one of the config's declared `tags`. Drives the sidebar's tag filter. */\n  tags?: Tag[]\n  status?: WindoStatus\n  description?: string\n  deprecation?: string\n  placement?: WindoPlacement\n  /** Initial component-local state. Its shape is the `State` generic; `ctx.state`/`ctx.setState` derive from it. */\n  state?: State\n  /** Out-of-band actions that drive state: toolbar buttons (`click`) and stage pointer triggers (`enter`/`exit`/`hover`). */\n  actions?: WindoAction<State>[]\n  /** zod schema: validator + parser for the JSON-editable prop subset. `z.output ⊆ Props`. */\n  configurableProps?: z.ZodType\n  /** Full props incl. functions/JSX. The editor's JSON overrides merge on top. */\n  defaultProps: WindoDefaultProps<Props, State>\n  /** Names of provider contexts this component opts into. */\n  uses?: string[]\n  variants?: WindoVariant<Props>[]\n  /** Authored documentation table (not derived from the schema). */\n  props?: WindoPropDoc[]\n  /** Optional authored code snippet for the Code tab. */\n  code?: (values: Props) => string\n  /** A local provider wrapping just this windo (in addition to `uses`). */\n  providers?: ComponentType<{ children: ReactNode; ctx: WindoRenderContext<State> }>\n  component: (props: Props, ctx: WindoRenderContext<State>) => ReactNode\n}\n\n/** Argument handed to the `windo(w => ...)` factory. */\nexport interface WindoFactoryArg<Groups extends readonly WindoGroup[], Contexts extends WindoContextMap, Tags extends readonly string[] = readonly string[]> {\n  /** Configured groups keyed by slug. */\n  groups: Record<Groups[number]['slug'], WindoGroup>\n  contexts: Contexts\n  /** The config's declared tags, in declaration order. */\n  tags: Tags\n}\n\n/**\n * The default export of a `*.windo.tsx` file. A branded, lazily-resolved\n * definition — the runtime calls `resolve(w)` with the config-derived factory arg.\n */\n// biome-ignore lint/suspicious/noExplicitAny: variance escape hatch for the heterogeneous WindoModule registry\nexport interface WindoModule<Props = any, State = any> {\n  readonly __windo: true\n  resolve: (w: WindoFactoryArg<readonly WindoGroup[], WindoContextMap>) => WindoDefinition<Props, State>\n}\n\n/* ------------------------------------------------------------------ *\n * Config\n * ------------------------------------------------------------------ */\n\nexport interface WindoConfig<Groups extends readonly WindoGroup[] = readonly WindoGroup[], Contexts extends WindoContextMap = WindoContextMap, Tags extends readonly string[] = readonly string[]> {\n  /** Configured groups. A component's `group` must be one of these slugs. */\n  groups: Groups\n  /** Named contexts available to components. */\n  contexts?: Contexts\n  /** The set of tags components may be assigned. A component's `tags` must be drawn from this list; the sidebar filters by them. */\n  tags?: Tags\n  /** Glob(s) for discovery, relative to project root. Default `**\\/*.windo.tsx`. */\n  include?: string | string[]\n  /** Title shown in the workbench chrome. */\n  title?: string\n}\n\n/* ------------------------------------------------------------------ *\n * Schema descriptor (crosses the iframe boundary; renders the controls)\n * ------------------------------------------------------------------ */\n\nexport type WindoControlKind = 'string' | 'number' | 'boolean' | 'enum' | 'date' | 'array' | 'object' | 'unknown'\n\nexport interface WindoControlDescriptor {\n  key: string\n  kind: WindoControlKind\n  optional: boolean\n  options?: string[]\n  min?: number\n  max?: number\n  description?: string\n}\n\nexport interface WindoSchemaDescriptor {\n  fields: WindoControlDescriptor[]\n}\n\n/* ------------------------------------------------------------------ *\n * Runtime manifest + protocol payloads\n * ------------------------------------------------------------------ */\n\n/** Serialisable metadata for one action — drives the canvas toolbar. */\nexport interface WindoActionMeta {\n  id: string\n  label: string\n  on: WindoActionTrigger\n}\n\n/** Static, serialisable metadata for one windo — drives the sidebar. */\nexport interface WindoManifestEntry {\n  id: string\n  title: string\n  group: string\n  tags: string[]\n  status: WindoStatus\n  description?: string\n  deprecation?: string\n  placement: WindoPlacement\n  uses: string[]\n  hasVariants: boolean\n  actions: WindoActionMeta[]\n  hasState: boolean\n}\n\nexport interface WindoVariantMeta {\n  label: string\n  props: Record<string, unknown>\n}\n\n/** Ambient environment pushed from the chrome down into the iframe. */\nexport interface WindoEnvState {\n  colorScheme: 'light' | 'dark'\n  viewport: WindoViewport\n  reducedMotion: boolean\n  direction: 'ltr' | 'rtl'\n  locale: string\n  /** Per-context control values, keyed by context name then control key. */\n  contexts: Record<string, Record<string, unknown>>\n}\n\nexport interface WindoLogEntry {\n  ts: number\n  args: unknown[]\n}\n\nexport interface WindoFieldError {\n  path: string\n  message: string\n}\n\n/* ------------------------------------------------------------------ *\n * Context metadata (serialisable; drives the chrome's Context panel)\n * ------------------------------------------------------------------ */\n\nexport interface WindoContextControlMeta {\n  key: string\n  type: WindoControlType\n  label?: string\n  options?: string[]\n  default: unknown\n  min?: number\n  max?: number\n  step?: number\n}\n\nexport interface WindoContextMeta {\n  name: string\n  label?: string\n  description?: string\n  /** True when the context contributes controls (ambient values). */\n  ambient: boolean\n  /** True when the context mounts a provider (opt-in via `uses`). */\n  hasProvider: boolean\n  controls: WindoContextControlMeta[]\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/define-config.ts","../src/descriptor.ts","../src/protocol.ts","../src/types.ts"],"sourcesContent":["// The authoring API. `defineWindoConfig` is the single entry point: it captures\n// the project's groups + contexts and hands back a `windo` factory whose `group`\n// field is type-checked against the configured slugs.\n\nimport type { ComponentType, ReactNode } from 'react'\nimport type { z } from 'zod'\nimport type { WindoConfig, WindoContextDefinition, WindoContextMap, WindoControlMap, WindoControlValues, WindoDefinition, WindoFactoryArg, WindoGroup, WindoModule, WindoRenderContext } from './types'\n\nexport interface DefineWindoConfigResult<Groups extends readonly WindoGroup[], Tags extends readonly string[], Contexts extends WindoContextMap> {\n  config: WindoConfig<Groups, Contexts, Tags>\n  windo: <Props, State = Record<string, never>>(\n    factory: (w: WindoFactoryArg<Groups, Contexts, Tags>) => WindoDefinition<Props, State, Groups[number]['slug'], Tags[number]>\n  ) => WindoModule<Props, State>\n}\n\nexport function defineWindoConfig<const Groups extends readonly WindoGroup[], const Tags extends readonly string[] = readonly [], Contexts extends WindoContextMap = Record<string, never>>(\n  config: WindoConfig<Groups, Contexts, Tags>\n): DefineWindoConfigResult<Groups, Tags, Contexts> {\n  function windo<Props, State = Record<string, never>>(\n    factory: (w: WindoFactoryArg<Groups, Contexts, Tags>) => WindoDefinition<Props, State, Groups[number]['slug'], Tags[number]>\n  ): WindoModule<Props, State> {\n    return {\n      __windo: true,\n      resolve: w => factory(w as unknown as WindoFactoryArg<Groups, Contexts, Tags>),\n    }\n  }\n  return { config, windo }\n}\n\n/**\n * Define a named context. A context can contribute ambient `controls` (values +\n * UI), a `provider` (mounted inside the iframe for components that opt in via\n * `uses`), or both.\n *\n * No cast: `def` is already structurally a `WindoContextDefinition<WindoControlValues<C>,\n * Provided>` (only `controls` widens, covariantly). The unavoidable variance — TS has\n * no existential type to hold contexts heterogeneous in `C` — is absorbed once, in\n * `WindoContextMap`, not here and not at call sites.\n */\nexport function defineContext<C extends WindoControlMap, Provided = WindoControlValues<C>>(def: {\n  label?: string\n  description?: string\n  controls?: C\n  provider?: ComponentType<{ children: ReactNode; values: WindoControlValues<C>; ctx: WindoRenderContext }>\n  resolve?: (values: WindoControlValues<C>, ctx: WindoRenderContext) => Provided\n}): WindoContextDefinition<WindoControlValues<C>, Provided> {\n  return def\n}\n\n/**\n * Bind a zod schema to a component's props. The generic carries the component's\n * prop type so the schema's output stays a subset of it; the returned schema is\n * the runtime validator + parser (`z.input` is the JSON edit surface, `z.output`\n * is what the component receives).\n */\nexport function configurableProps<P>() {\n  return <S extends z.ZodType<Partial<P>>>(schema: S): S => schema\n}\n","// Walk a zod schema into a serialisable descriptor that can cross the iframe\n// boundary and render the Controls/Schema UI. We lean on `z.toJSONSchema` (zod\n// v4) for the input shape (enum options, min/max, optionality), then enrich the\n// kind from the zod node's own type tag — some types (Date, Map, Set) are\n// unrepresentable in JSON Schema and come back as `{}`, but their zod `def.type`\n// is exact. The live schema (with transforms/coerce/refine) stays in the iframe\n// and does the actual parsing — only this descriptor travels.\n\nimport { z } from 'zod'\nimport type { WindoControlDescriptor, WindoControlKind, WindoSchemaDescriptor } from './types'\n\ninterface JsonNode {\n  type?: string | string[]\n  enum?: unknown[]\n  const?: unknown\n  format?: string\n  properties?: Record<string, JsonNode>\n  required?: string[]\n  items?: JsonNode\n  anyOf?: JsonNode[]\n  oneOf?: JsonNode[]\n  allOf?: JsonNode[]\n  minimum?: number\n  maximum?: number\n  description?: string\n}\n\nexport function describeSchema(schema: z.ZodType | undefined | null): WindoSchemaDescriptor {\n  if (!schema) return { fields: [] }\n  let json: JsonNode\n  try {\n    json = z.toJSONSchema(schema, { io: 'input', unrepresentable: 'any' }) as JsonNode\n  } catch {\n    return { fields: [] }\n  }\n  const root = unwrap(json)\n  const properties = root.properties ?? {}\n  const required = new Set(root.required ?? [])\n  const zodKinds = shapeKinds(schema)\n  const fields: WindoControlDescriptor[] = Object.keys(properties).map(key => fieldFrom(key, properties[key], required.has(key), zodKinds[key]))\n  return { fields }\n}\n\n// JSON Schema often wraps the object in anyOf (for optional/nullable). Find the\n// node that actually carries the object's properties.\nfunction unwrap(node: JsonNode): JsonNode {\n  if (node.properties) return node\n  const branches = node.anyOf ?? node.oneOf ?? node.allOf\n  if (branches) {\n    const withProps = branches.find(b => b.properties)\n    if (withProps) return withProps\n  }\n  return node\n}\n\nfunction fieldFrom(key: string, node: JsonNode, isRequired: boolean, zodKind?: WindoControlKind): WindoControlDescriptor {\n  const inner = collapseNullable(node)\n  let kind = kindOf(inner)\n  // The zod tag wins for types JSON Schema can't express (date/array/object that\n  // came back as {}), and as a fallback whenever the JSON kind is unknown.\n  if (zodKind && (kind === 'unknown' || zodKind === 'date')) kind = zodKind\n  const descriptor: WindoControlDescriptor = {\n    key,\n    kind,\n    optional: !isRequired || isNullable(node),\n  }\n  if (inner.description) descriptor.description = inner.description\n  const options = enumOptions(inner)\n  if (options) descriptor.options = options\n  if (typeof inner.minimum === 'number') descriptor.min = inner.minimum\n  if (typeof inner.maximum === 'number') descriptor.max = inner.maximum\n  return descriptor\n}\n\nfunction isNullable(node: JsonNode): boolean {\n  const branches = node.anyOf ?? node.oneOf\n  if (!branches) return false\n  return branches.some(b => b.type === 'null')\n}\n\n// Strip a `{ anyOf: [T, null] }` wrapper down to T.\nfunction collapseNullable(node: JsonNode): JsonNode {\n  const branches = node.anyOf ?? node.oneOf\n  if (!branches) return node\n  const nonNull = branches.filter(b => b.type !== 'null')\n  if (nonNull.length === 1) return nonNull[0]\n  return node\n}\n\nfunction enumOptions(node: JsonNode): string[] | undefined {\n  if (Array.isArray(node.enum)) return node.enum.map(v => String(v))\n  const branches = node.anyOf ?? node.oneOf\n  if (branches?.every(b => b.const !== undefined)) {\n    return branches.map(b => String(b.const))\n  }\n  return undefined\n}\n\nfunction kindOf(node: JsonNode): WindoControlKind {\n  if (Array.isArray(node.enum) || (node.anyOf?.every(b => b.const !== undefined) ?? false)) return 'enum'\n  if (node.format === 'date-time' || node.format === 'date') return 'date'\n  const type = Array.isArray(node.type) ? node.type.find(t => t !== 'null') : node.type\n  switch (type) {\n    case 'string':\n      return 'string'\n    case 'number':\n    case 'integer':\n      return 'number'\n    case 'boolean':\n      return 'boolean'\n    case 'array':\n      return 'array'\n    case 'object':\n      return 'object'\n    default:\n      return 'unknown'\n  }\n}\n\n/* ------------------------------------------------------------------ *\n * zod node introspection (the kind source of truth for unrepresentable types)\n * ------------------------------------------------------------------ */\n\ninterface ZodDefLike {\n  type?: string\n  innerType?: unknown\n}\n\nfunction zodDef(node: unknown): ZodDefLike | undefined {\n  const n = node as { def?: ZodDefLike; _zod?: { def?: ZodDefLike } } | null\n  if (!n || typeof n !== 'object') return undefined\n  return n.def ?? n._zod?.def\n}\n\nconst ZOD_WRAPPERS = new Set(['optional', 'nullable', 'default', 'prefault', 'catch', 'readonly', 'nonoptional', 'lazy'])\n\n// Unwrap optional/nullable/default/... down to the meaningful inner node.\nfunction unwrapZodDef(node: unknown): ZodDefLike | undefined {\n  let def = zodDef(node)\n  let guard = 0\n  while (def && def.innerType && ZOD_WRAPPERS.has(def.type ?? '') && guard++ < 16) {\n    def = zodDef(def.innerType)\n  }\n  return def\n}\n\nfunction mapZodType(type: string | undefined): WindoControlKind | undefined {\n  switch (type) {\n    case 'date':\n      return 'date'\n    case 'string':\n      return 'string'\n    case 'number':\n    case 'int':\n    case 'bigint':\n      return 'number'\n    case 'boolean':\n      return 'boolean'\n    case 'array':\n    case 'set':\n    case 'tuple':\n      return 'array'\n    case 'object':\n    case 'record':\n    case 'map':\n      return 'object'\n    case 'enum':\n    case 'literal':\n      return 'enum'\n    default:\n      return undefined\n  }\n}\n\n// Per-field kind read straight from the zod object's shape.\nfunction shapeKinds(schema: z.ZodType): Record<string, WindoControlKind> {\n  const shape = (schema as { shape?: Record<string, unknown> }).shape\n  if (!shape || typeof shape !== 'object') return {}\n  const out: Record<string, WindoControlKind> = {}\n  for (const key of Object.keys(shape)) {\n    const kind = mapZodType(unwrapZodDef(shape[key])?.type)\n    if (kind) out[key] = kind\n  }\n  return out\n}\n","// The chrome <-> iframe postMessage contract. The schema itself never crosses\n// the boundary: the iframe walks it into a serialisable descriptor, the chrome\n// sends candidate JSON down, the iframe parses and reports back. Every payload\n// here is plain JSON.\n\nimport type { WindoContextMeta, WindoEnvState, WindoFieldError, WindoGroup, WindoLogEntry, WindoManifestEntry, WindoPropDoc, WindoSchemaDescriptor, WindoVariantMeta } from './types'\n\nexport const WINDO_MSG = 'windo'\n\n/** chrome -> iframe */\nexport type WindoHostMessage =\n  | { source: typeof WINDO_MSG; dir: 'host'; type: 'request-manifest' }\n  | { source: typeof WINDO_MSG; dir: 'host'; type: 'select'; id: string }\n  | { source: typeof WINDO_MSG; dir: 'host'; type: 'set-props'; id: string; json: string }\n  | { source: typeof WINDO_MSG; dir: 'host'; type: 'set-env'; env: WindoEnvState }\n  | { source: typeof WINDO_MSG; dir: 'host'; type: 'set-ctx-state'; state: Record<string, unknown> }\n  | { source: typeof WINDO_MSG; dir: 'host'; type: 'invoke-action'; id: string; actionId: string }\n\n/** iframe -> chrome */\nexport type WindoPreviewMessage =\n  | { source: typeof WINDO_MSG; dir: 'preview'; type: 'ready' }\n  | {\n      source: typeof WINDO_MSG\n      dir: 'preview'\n      type: 'manifest'\n      title: string\n      entries: WindoManifestEntry[]\n      groups: WindoGroup[]\n      tags: string[]\n      contexts: WindoContextMeta[]\n      /** Initial shared state from the config — seeds the chrome's editable strip. */\n      ctxState: Record<string, unknown>\n    }\n  | {\n      source: typeof WINDO_MSG\n      dir: 'preview'\n      type: 'describe'\n      id: string\n      descriptor: WindoSchemaDescriptor\n      props: WindoPropDoc[]\n      variants: WindoVariantMeta[]\n      defaults: unknown\n      code: string | null\n    }\n  | { source: typeof WINDO_MSG; dir: 'preview'; type: 'parse-ok'; id: string }\n  | { source: typeof WINDO_MSG; dir: 'preview'; type: 'parse-error'; id: string; errors: WindoFieldError[] }\n  | { source: typeof WINDO_MSG; dir: 'preview'; type: 'log'; entry: WindoLogEntry }\n  | { source: typeof WINDO_MSG; dir: 'preview'; type: 'state'; id: string; state: Record<string, unknown>; actions: { id: string; disabled: boolean }[] }\n  | { source: typeof WINDO_MSG; dir: 'preview'; type: 'ctx-state'; state: Record<string, unknown> }\n  | { source: typeof WINDO_MSG; dir: 'preview'; type: 'color-scheme'; colorScheme: 'light' | 'dark' }\n  | { source: typeof WINDO_MSG; dir: 'preview'; type: 'render-error'; id: string; message: string; stack?: string }\n\nexport type WindoMessage = WindoHostMessage | WindoPreviewMessage\n\nexport function isWindoMessage(data: unknown): data is WindoMessage {\n  return typeof data === 'object' && data !== null && (data as { source?: unknown }).source === WINDO_MSG\n}\n\nexport function isHostMessage(msg: WindoMessage): msg is WindoHostMessage {\n  return msg.dir === 'host'\n}\n\nexport function isPreviewMessage(msg: WindoMessage): msg is WindoPreviewMessage {\n  return msg.dir === 'preview'\n}\n","// Core type system for windo. Everything — the authoring API, the iframe\n// preview runtime, the chrome UI, and the postMessage protocol — is typed\n// against the contracts in this file.\n\nimport type { ComponentType, ReactNode } from 'react'\nimport type { z } from 'zod'\n\n/* ------------------------------------------------------------------ *\n * Primitives\n * ------------------------------------------------------------------ */\n\nexport type WindoStatus = 'stable' | 'beta' | 'deprecated'\n\nexport const WINDO_STATUSES: readonly WindoStatus[] = ['stable', 'beta', 'deprecated']\n\n/** Anchor a component within the canvas frame. */\nexport type WindoPlacementBase = 'center' | 'fill' | 'top' | 'bottom' | 'left' | 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'\n\n/**\n * Where a component renders inside the canvas frame. Placements render flush by\n * default; append `-padding` to inset the component from the frame edges\n * (e.g. `top` sits flush at the top, `top-padding` adds breathing room).\n */\nexport type WindoPlacement = WindoPlacementBase | `${WindoPlacementBase}-padding`\n\nconst WINDO_PLACEMENT_BASE: readonly WindoPlacementBase[] = ['center', 'fill', 'top', 'bottom', 'left', 'right', 'top-left', 'top-right', 'bottom-left', 'bottom-right']\n\nexport const WINDO_PLACEMENTS: readonly WindoPlacement[] = [...WINDO_PLACEMENT_BASE, ...WINDO_PLACEMENT_BASE.map(p => `${p}-padding` as WindoPlacement)]\n\n/** A configured group. Components reference a group by its `slug`. */\nexport interface WindoGroup {\n  name: string\n  slug: string\n  description?: string\n}\n\n/* ------------------------------------------------------------------ *\n * Context system\n * ------------------------------------------------------------------ */\n\nexport type WindoControlType = 'enum' | 'boolean' | 'string' | 'number'\n\n/** A single ambient control: a value plus the metadata to render its toggle. */\nexport interface WindoControlSpec<T = unknown> {\n  type: WindoControlType\n  label?: string\n  default: T\n  options?: readonly string[]\n  min?: number\n  max?: number\n  step?: number\n}\n\nexport type WindoControlMap = Record<string, WindoControlSpec>\n\n/** Resolve a control map to the value object it produces. */\nexport type WindoControlValues<C extends WindoControlMap> = {\n  [K in keyof C]: C[K] extends WindoControlSpec<infer T> ? T : never\n}\n\n/**\n * A named context. Two capabilities, either or both:\n *  - `controls`  → ambient values + UI toggles (free, no opt-in needed)\n *  - `provider`  → a React wrapper, mounted inside the iframe around components\n *                  that opt in via `uses`\n */\nexport interface WindoContextDefinition<Values = unknown, Provided = Values> {\n  label?: string\n  description?: string\n  controls?: WindoControlMap\n  provider?: ComponentType<{ children: ReactNode; values: Values; ctx: WindoRenderContext }>\n  /** Derive the value exposed on `ctx.contexts[name]`. Defaults to the control values. */\n  resolve?: (values: Values, ctx: WindoRenderContext) => Provided\n}\n\n// Contexts are each generic over a different control map `C`; TS has no existential\n// to hold `exists C. WindoContextDefinition<WindoControlValues<C>>`. `Values` sits in\n// contravariant positions (provider props, resolve arg) so no precise common supertype\n// exists — `any` is the single, contained variance hatch for this heterogeneous\n// registry. Mirrors WindoModule. Definition sites stay precise; this only erases at the\n// point of collection.\n// biome-ignore lint/suspicious/noExplicitAny: existential variance hatch for the heterogeneous context registry\nexport type WindoContextMap = Record<string, WindoContextDefinition<any, any>>\n\n/* ------------------------------------------------------------------ *\n * Render-time context\n * ------------------------------------------------------------------ */\n\nexport interface WindoViewport {\n  width: number\n  height: number\n  name: 'mobile' | 'tablet' | 'desktop'\n}\n\n/** Console channel: `ctx.logger.log(…)` posts an entry to the chrome's Console tab. */\nexport interface WindoLogger {\n  log: (...args: unknown[]) => void\n}\n\n/** How an action fires. `click` renders a toolbar button; the rest bind to the stage's pointer events. */\nexport type WindoActionTrigger = 'click' | 'enter' | 'exit' | 'hover'\n\nexport const WINDO_ACTION_TRIGGERS: readonly WindoActionTrigger[] = ['click', 'enter', 'exit', 'hover']\n\n/**\n * An out-of-band action that drives a component's state. `click` actions render as\n * toolbar buttons; `enter`/`exit`/`hover` bind to the stage's pointer events. `run`\n * receives the live ctx and an `active` flag — for `hover` it is `true` on\n * pointer-enter and `false` on pointer-leave; for the others it is always `true`.\n */\nexport interface WindoAction<State = unknown> {\n  label: string\n  /** Defaults to `click`. */\n  on?: WindoActionTrigger\n  run: (ctx: WindoRenderContext<State>, active: boolean) => void\n  /** Greys out a `click` action's toolbar button. Evaluated against the live state. */\n  disabled?: (ctx: WindoRenderContext<State>) => boolean\n}\n\n/** Live environment handed to every render-time function inside the iframe. */\nexport interface WindoRenderContext<State = unknown> {\n  colorScheme: 'light' | 'dark'\n  viewport: WindoViewport\n  reducedMotion: boolean\n  direction: 'ltr' | 'rtl'\n  locale: string\n  logger: WindoLogger\n  /** Current component-local state, typed by the windo's `State` generic. */\n  state: State\n  /** Merge a patch into the component-local state and re-render. */\n  setState: (patch: Partial<State>) => void\n  /** Resolved values of opted-in contexts, keyed by context name. */\n  contexts: Record<string, unknown>\n  /**\n   * Shared, cross-component state seeded from the config's `ctxState`. Unlike\n   * `state` (per-windo, reset on selection), this persists across selection and\n   * is global: any component can read it and write it via `setCtxState`. Use it\n   * to drive providers that wrap every component — e.g. a theme provider toggled\n   * from any component on the canvas.\n   */\n  ctxState: Record<string, unknown>\n  /** Merge a patch into the shared `ctxState` and re-render every consumer. */\n  setCtxState: (patch: Record<string, unknown>) => void\n  /** Set the canvas colour scheme from a component or action. */\n  setColorScheme: (scheme: 'light' | 'dark') => void\n  /** Flip the canvas colour scheme between light and dark. */\n  toggleTheme: () => void\n}\n\n/* ------------------------------------------------------------------ *\n * Authoring API\n * ------------------------------------------------------------------ */\n\n/** A variant: a label plus a partial prop patch. Renders in the gallery and is click-to-apply. */\nexport interface WindoVariant<Props> {\n  label: string\n  props: Partial<Props>\n}\n\n/** A row in the authored Props documentation table. */\nexport interface WindoPropDoc {\n  name: string\n  type: string\n  default?: string\n  desc?: string\n}\n\n/** A value that may be authored statically or as a context-aware `ctx => value` function resolved at render-time. */\nexport type Ctxual<T, State = unknown> = T | ((ctx: WindoRenderContext<State>) => T)\n\n/** The ctx surface available while resolving a windo's initial state — the render-time `state`/`setState` pair is excluded because it does not exist yet. */\nexport type WindoInitContext<State = unknown> = Omit<WindoRenderContext<State>, 'state' | 'setState'>\n\nexport type WindoDefaultProps<Props, State = unknown> = Ctxual<Props, State>\n\n/**\n * The object returned by a `windo(...)` factory.\n *\n * Keystone rule: the surrounding factory runs ONCE (definition-time) for static\n * fields (title, group, schema). Every function field below — `defaultProps`,\n * `actions`, `providers`, `component` — runs at render-time with the live `ctx`.\n * Never close over live values in the static factory body.\n */\nexport interface WindoDefinition<Props = unknown, State = unknown, GroupSlug extends string = string, Tag extends string = string> {\n  title: string\n  group: GroupSlug\n  /** Tags this component carries. Each must be one of the config's declared `tags`. Drives the sidebar's tag filter. */\n  tags?: Tag[]\n  status?: WindoStatus\n  description?: string\n  deprecation?: string\n  /** Where the component anchors in the canvas frame. Either a static placement or a function resolved with the live `ctx`. */\n  placement?: Ctxual<WindoPlacement, State>\n  /** Initial component-local state. Its shape is the `State` generic; `ctx.state`/`ctx.setState` derive from it. Either a static value or a function resolved with the init `ctx` (no `state`/`setState`) when the component is selected. */\n  state?: State | ((ctx: WindoInitContext<State>) => State)\n  /** Out-of-band actions that drive state: toolbar buttons (`click`) and stage pointer triggers (`enter`/`exit`/`hover`). */\n  actions?: WindoAction<State>[]\n  /** zod schema: validator + parser for the JSON-editable prop subset. `z.output ⊆ Props`. */\n  configurableProps?: z.ZodType\n  /** Full props incl. functions/JSX. The editor's JSON overrides merge on top. */\n  defaultProps: WindoDefaultProps<Props, State>\n  /** Names of provider contexts this component opts into. */\n  uses?: string[]\n  /** Gallery variants. Either a static array or a function resolved with the live `ctx` when the component is selected. */\n  variants?: Ctxual<WindoVariant<Props>[], State>\n  /** Authored documentation table (not derived from the schema). Either a static array or a function resolved with the live `ctx` when the component is selected. */\n  props?: Ctxual<WindoPropDoc[], State>\n  /** Optional authored code snippet for the Code tab, resolved with the JSON-editable values and the live `ctx`. */\n  code?: (values: Props, ctx: WindoRenderContext<State>) => string\n  /** A local provider wrapping just this windo (in addition to `uses`). */\n  providers?: ComponentType<{ children: ReactNode; ctx: WindoRenderContext<State> }>\n  component: (props: Props, ctx: WindoRenderContext<State>) => ReactNode\n}\n\n/** Argument handed to the `windo(w => ...)` factory. */\nexport interface WindoFactoryArg<Groups extends readonly WindoGroup[], Contexts extends WindoContextMap, Tags extends readonly string[] = readonly string[]> {\n  /** Configured groups keyed by slug. */\n  groups: Record<Groups[number]['slug'], WindoGroup>\n  contexts: Contexts\n  /** The config's declared tags, in declaration order. */\n  tags: Tags\n}\n\n/**\n * The default export of a `*.windo.tsx` file. A branded, lazily-resolved\n * definition — the runtime calls `resolve(w)` with the config-derived factory arg.\n */\n// biome-ignore lint/suspicious/noExplicitAny: variance escape hatch for the heterogeneous WindoModule registry\nexport interface WindoModule<Props = any, State = any> {\n  readonly __windo: true\n  resolve: (w: WindoFactoryArg<readonly WindoGroup[], WindoContextMap>) => WindoDefinition<Props, State>\n}\n\n/* ------------------------------------------------------------------ *\n * Config\n * ------------------------------------------------------------------ */\n\nexport interface WindoConfig<Groups extends readonly WindoGroup[] = readonly WindoGroup[], Contexts extends WindoContextMap = WindoContextMap, Tags extends readonly string[] = readonly string[]> {\n  /** Configured groups. A component's `group` must be one of these slugs. */\n  groups: Groups\n  /** Named contexts available to components. */\n  contexts?: Contexts\n  /** The set of tags components may be assigned. A component's `tags` must be drawn from this list; the sidebar filters by them. */\n  tags?: Tags\n  /** Initial shared state exposed on `ctx.ctxState`. Global across every component and persisted across selection — write it from any component via `ctx.setCtxState`. */\n  ctxState?: Record<string, unknown>\n  /** Glob(s) for discovery, relative to project root. Default `**\\/*.windo.tsx`. */\n  include?: string | string[]\n  /** Title shown in the workbench chrome. */\n  title?: string\n}\n\n/* ------------------------------------------------------------------ *\n * Schema descriptor (crosses the iframe boundary; renders the controls)\n * ------------------------------------------------------------------ */\n\nexport type WindoControlKind = 'string' | 'number' | 'boolean' | 'enum' | 'date' | 'array' | 'object' | 'unknown'\n\nexport interface WindoControlDescriptor {\n  key: string\n  kind: WindoControlKind\n  optional: boolean\n  options?: string[]\n  min?: number\n  max?: number\n  description?: string\n}\n\nexport interface WindoSchemaDescriptor {\n  fields: WindoControlDescriptor[]\n}\n\n/* ------------------------------------------------------------------ *\n * Runtime manifest + protocol payloads\n * ------------------------------------------------------------------ */\n\n/** Serialisable metadata for one action — drives the canvas toolbar. */\nexport interface WindoActionMeta {\n  id: string\n  label: string\n  on: WindoActionTrigger\n}\n\n/** Static, serialisable metadata for one windo — drives the sidebar. */\nexport interface WindoManifestEntry {\n  id: string\n  title: string\n  group: string\n  tags: string[]\n  status: WindoStatus\n  description?: string\n  deprecation?: string\n  placement: WindoPlacement\n  uses: string[]\n  hasVariants: boolean\n  actions: WindoActionMeta[]\n  hasState: boolean\n}\n\nexport interface WindoVariantMeta {\n  label: string\n  props: Record<string, unknown>\n}\n\n/** Ambient environment pushed from the chrome down into the iframe. */\nexport interface WindoEnvState {\n  colorScheme: 'light' | 'dark'\n  viewport: WindoViewport\n  reducedMotion: boolean\n  direction: 'ltr' | 'rtl'\n  locale: string\n  /** Per-context control values, keyed by context name then control key. */\n  contexts: Record<string, Record<string, unknown>>\n}\n\nexport interface WindoLogEntry {\n  ts: number\n  args: unknown[]\n}\n\nexport interface WindoFieldError {\n  path: string\n  message: string\n}\n\n/* ------------------------------------------------------------------ *\n * Context metadata (serialisable; drives the chrome's Context panel)\n * ------------------------------------------------------------------ */\n\nexport interface WindoContextControlMeta {\n  key: string\n  type: WindoControlType\n  label?: string\n  options?: string[]\n  default: unknown\n  min?: number\n  max?: number\n  step?: number\n}\n\nexport interface WindoContextMeta {\n  name: string\n  label?: string\n  description?: string\n  /** True when the context contributes controls (ambient values). */\n  ambient: boolean\n  /** True when the context mounts a provider (opt-in via `uses`). */\n  hasProvider: boolean\n  controls: WindoContextControlMeta[]\n}\n"],"mappings":";AAeO,SAAS,kBACd,QACiD;AACjD,WAAS,MACP,SAC2B;AAC3B,WAAO;AAAA,MACL,SAAS;AAAA,MACT,SAAS,OAAK,QAAQ,CAAuD;AAAA,IAC/E;AAAA,EACF;AACA,SAAO,EAAE,QAAQ,MAAM;AACzB;AAYO,SAAS,cAA2E,KAM/B;AAC1D,SAAO;AACT;AAQO,SAAS,oBAAuB;AACrC,SAAO,CAAkC,WAAiB;AAC5D;;;ACjDA,SAAS,SAAS;AAmBX,SAAS,eAAe,QAA6D;AAC1F,MAAI,CAAC,OAAQ,QAAO,EAAE,QAAQ,CAAC,EAAE;AACjC,MAAI;AACJ,MAAI;AACF,WAAO,EAAE,aAAa,QAAQ,EAAE,IAAI,SAAS,iBAAiB,MAAM,CAAC;AAAA,EACvE,QAAQ;AACN,WAAO,EAAE,QAAQ,CAAC,EAAE;AAAA,EACtB;AACA,QAAM,OAAO,OAAO,IAAI;AACxB,QAAM,aAAa,KAAK,cAAc,CAAC;AACvC,QAAM,WAAW,IAAI,IAAI,KAAK,YAAY,CAAC,CAAC;AAC5C,QAAM,WAAW,WAAW,MAAM;AAClC,QAAM,SAAmC,OAAO,KAAK,UAAU,EAAE,IAAI,SAAO,UAAU,KAAK,WAAW,GAAG,GAAG,SAAS,IAAI,GAAG,GAAG,SAAS,GAAG,CAAC,CAAC;AAC7I,SAAO,EAAE,OAAO;AAClB;AAIA,SAAS,OAAO,MAA0B;AACxC,MAAI,KAAK,WAAY,QAAO;AAC5B,QAAM,WAAW,KAAK,SAAS,KAAK,SAAS,KAAK;AAClD,MAAI,UAAU;AACZ,UAAM,YAAY,SAAS,KAAK,OAAK,EAAE,UAAU;AACjD,QAAI,UAAW,QAAO;AAAA,EACxB;AACA,SAAO;AACT;AAEA,SAAS,UAAU,KAAa,MAAgB,YAAqB,SAAoD;AACvH,QAAM,QAAQ,iBAAiB,IAAI;AACnC,MAAI,OAAO,OAAO,KAAK;AAGvB,MAAI,YAAY,SAAS,aAAa,YAAY,QAAS,QAAO;AAClE,QAAM,aAAqC;AAAA,IACzC;AAAA,IACA;AAAA,IACA,UAAU,CAAC,cAAc,WAAW,IAAI;AAAA,EAC1C;AACA,MAAI,MAAM,YAAa,YAAW,cAAc,MAAM;AACtD,QAAM,UAAU,YAAY,KAAK;AACjC,MAAI,QAAS,YAAW,UAAU;AAClC,MAAI,OAAO,MAAM,YAAY,SAAU,YAAW,MAAM,MAAM;AAC9D,MAAI,OAAO,MAAM,YAAY,SAAU,YAAW,MAAM,MAAM;AAC9D,SAAO;AACT;AAEA,SAAS,WAAW,MAAyB;AAC3C,QAAM,WAAW,KAAK,SAAS,KAAK;AACpC,MAAI,CAAC,SAAU,QAAO;AACtB,SAAO,SAAS,KAAK,OAAK,EAAE,SAAS,MAAM;AAC7C;AAGA,SAAS,iBAAiB,MAA0B;AAClD,QAAM,WAAW,KAAK,SAAS,KAAK;AACpC,MAAI,CAAC,SAAU,QAAO;AACtB,QAAM,UAAU,SAAS,OAAO,OAAK,EAAE,SAAS,MAAM;AACtD,MAAI,QAAQ,WAAW,EAAG,QAAO,QAAQ,CAAC;AAC1C,SAAO;AACT;AAEA,SAAS,YAAY,MAAsC;AACzD,MAAI,MAAM,QAAQ,KAAK,IAAI,EAAG,QAAO,KAAK,KAAK,IAAI,OAAK,OAAO,CAAC,CAAC;AACjE,QAAM,WAAW,KAAK,SAAS,KAAK;AACpC,MAAI,UAAU,MAAM,OAAK,EAAE,UAAU,MAAS,GAAG;AAC/C,WAAO,SAAS,IAAI,OAAK,OAAO,EAAE,KAAK,CAAC;AAAA,EAC1C;AACA,SAAO;AACT;AAEA,SAAS,OAAO,MAAkC;AAChD,MAAI,MAAM,QAAQ,KAAK,IAAI,MAAM,KAAK,OAAO,MAAM,OAAK,EAAE,UAAU,MAAS,KAAK,OAAQ,QAAO;AACjG,MAAI,KAAK,WAAW,eAAe,KAAK,WAAW,OAAQ,QAAO;AAClE,QAAM,OAAO,MAAM,QAAQ,KAAK,IAAI,IAAI,KAAK,KAAK,KAAK,OAAK,MAAM,MAAM,IAAI,KAAK;AACjF,UAAQ,MAAM;AAAA,IACZ,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AAAA,IACL,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT;AACE,aAAO;AAAA,EACX;AACF;AAWA,SAAS,OAAO,MAAuC;AACrD,QAAM,IAAI;AACV,MAAI,CAAC,KAAK,OAAO,MAAM,SAAU,QAAO;AACxC,SAAO,EAAE,OAAO,EAAE,MAAM;AAC1B;AAEA,IAAM,eAAe,oBAAI,IAAI,CAAC,YAAY,YAAY,WAAW,YAAY,SAAS,YAAY,eAAe,MAAM,CAAC;AAGxH,SAAS,aAAa,MAAuC;AAC3D,MAAI,MAAM,OAAO,IAAI;AACrB,MAAI,QAAQ;AACZ,SAAO,OAAO,IAAI,aAAa,aAAa,IAAI,IAAI,QAAQ,EAAE,KAAK,UAAU,IAAI;AAC/E,UAAM,OAAO,IAAI,SAAS;AAAA,EAC5B;AACA,SAAO;AACT;AAEA,SAAS,WAAW,MAAwD;AAC1E,UAAQ,MAAM;AAAA,IACZ,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AAAA,IACL,KAAK;AAAA,IACL,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AAAA,IACL,KAAK;AAAA,IACL,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AAAA,IACL,KAAK;AAAA,IACL,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AAAA,IACL,KAAK;AACH,aAAO;AAAA,IACT;AACE,aAAO;AAAA,EACX;AACF;AAGA,SAAS,WAAW,QAAqD;AACvE,QAAM,QAAS,OAA+C;AAC9D,MAAI,CAAC,SAAS,OAAO,UAAU,SAAU,QAAO,CAAC;AACjD,QAAM,MAAwC,CAAC;AAC/C,aAAW,OAAO,OAAO,KAAK,KAAK,GAAG;AACpC,UAAM,OAAO,WAAW,aAAa,MAAM,GAAG,CAAC,GAAG,IAAI;AACtD,QAAI,KAAM,KAAI,GAAG,IAAI;AAAA,EACvB;AACA,SAAO;AACT;;;ACjLO,IAAM,YAAY;AA+ClB,SAAS,eAAe,MAAqC;AAClE,SAAO,OAAO,SAAS,YAAY,SAAS,QAAS,KAA8B,WAAW;AAChG;AAEO,SAAS,cAAc,KAA4C;AACxE,SAAO,IAAI,QAAQ;AACrB;AAEO,SAAS,iBAAiB,KAA+C;AAC9E,SAAO,IAAI,QAAQ;AACrB;;;ACnDO,IAAM,iBAAyC,CAAC,UAAU,QAAQ,YAAY;AAYrF,IAAM,uBAAsD,CAAC,UAAU,QAAQ,OAAO,UAAU,QAAQ,SAAS,YAAY,aAAa,eAAe,cAAc;AAEhK,IAAM,mBAA8C,CAAC,GAAG,sBAAsB,GAAG,qBAAqB,IAAI,OAAK,GAAG,CAAC,UAA4B,CAAC;AA2EhJ,IAAM,wBAAuD,CAAC,SAAS,SAAS,QAAQ,OAAO;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@westopp/windo",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Zero-infra component canvas — point it at *.windo.tsx files and get a resizable preview with live props, variants, and context",
   "license": "MIT",
   "type": "module",

package/src/cli/index.ts

@@ -10,7 +10,7 @@ import pc from 'picocolors'
 import { build, createServer, preview } from 'vite'
 import { windoPlugin } from '../plugin'
 
-const VERSION = '0.1.0'
+const VERSION = '0.1.2'
 
 const USAGE = `
 ${pc.bold('windo')} ${pc.dim(`v${VERSION}`)} — zero-infra component canvas

package/src/client/App.tsx

@@ -67,6 +67,14 @@ export function App() {
   const [grid, setGridState] = useState<CanvasGridOpts>(() => loadJSON<CanvasGridOpts>('windo:grid', CANVAS_GRID_DEFAULTS))
   const [env, setEnv] = useState<ChromeEnv>(() => ({ ...loadJSON<ChromeEnv>('windo:env', DEFAULT_ENV), colorScheme: loadString('windo:theme', 'light') as ThemeMode }))
 
+  // Shared, cross-component state. The chrome holds the canonical, persisted copy;
+  // the preview owns a working copy it can write from any component. They stay in
+  // sync via the bridge: component writes echo up (adopted below), chrome edits and
+  // reload re-syncs push down.
+  const [ctxState, setCtxState] = useState<Record<string, unknown>>(() => loadJSON<Record<string, unknown>>('windo:ctx-state', {}))
+  const ctxStateRef = useRef(ctxState)
+  ctxStateRef.current = ctxState
+
   const [draftById, setDraftById] = useState<Record<string, string>>({})
   // Last JSON pushed to the preview, per id. `dirty` = draft differs from this.
   // Every push (seed, save, reset, variant, reload re-sync) updates it, so the
@@ -104,6 +112,7 @@ export function App() {
   useEffect(() => saveJSON('windo:zoom', zoom), [zoom])
   useEffect(() => saveJSON('windo:grid', grid), [grid])
   useEffect(() => saveJSON('windo:env', env), [env])
+  useEffect(() => saveJSON('windo:ctx-state', ctxState), [ctxState])
 
   // ── selection wiring ───────────────────────────────────────────────────
   useEffect(() => {
@@ -143,6 +152,33 @@ export function App() {
     bridge.setEnv(next)
   }, [env, width, height, theme, bridge.setEnv, bridge.readyNonce])
 
+  // ── shared state (ctxState) sync ──────────────────────────────────────────
+  // Seed the canonical from the config defaults, filling only keys the chrome
+  // hasn't already persisted (persisted edits win).
+  useEffect(() => {
+    if (!Object.keys(bridge.ctxStateDefaults).length) return
+    setCtxState(prev => ({ ...bridge.ctxStateDefaults, ...prev }))
+  }, [bridge.ctxStateDefaults])
+
+  // Adopt component-driven writes echoed up from the preview (preview is the live
+  // truth for those). The chrome's own pushes don't echo, so this never loops.
+  useEffect(() => {
+    if (!Object.keys(bridge.ctxState).length) return
+    setCtxState(prev => ({ ...prev, ...bridge.ctxState }))
+  }, [bridge.ctxState])
+
+  // Re-sync the canonical down on every (re)ready — the iframe reloads on HMR and
+  // re-seeds from config defaults, so we re-assert the persisted shared state.
+  useEffect(() => {
+    if (Object.keys(ctxStateRef.current).length) bridge.setCtxState(ctxStateRef.current)
+  }, [bridge.setCtxState, bridge.readyNonce])
+
+  // Follow a component's `toggleTheme`/`setColorScheme` push (depends only on the
+  // echo, never on `theme` — so a topbar toggle is never reverted by a stale echo).
+  useEffect(() => {
+    if (bridge.colorScheme) setTheme(bridge.colorScheme.value)
+  }, [bridge.colorScheme])
+
   // ── draft commit / variant ─────────────────────────────────────────────
   function setValuesJson(json: string) {
     if (!selected) return
@@ -196,6 +232,14 @@ export function App() {
     }))
   }
 
+  // Edit one key of the shared state from the chrome: update the canonical and
+  // push the whole object down (the preview adopts it without echoing back).
+  function setCtxStateValue(key: string, value: unknown) {
+    const next = { ...ctxStateRef.current, [key]: value }
+    setCtxState(next)
+    bridge.setCtxState(next)
+  }
+
   function setGrid(patch: Partial<CanvasGridOpts> | null) {
     if (patch === null) {
       setGridState(CANVAS_GRID_DEFAULTS)
@@ -276,6 +320,8 @@ export function App() {
       logs={bridge.logs}
       clearLogs={bridge.clearLogs}
       state={stateForEntry}
+      ctxState={ctxState}
+      setCtxStateValue={setCtxStateValue}
       contexts={contextsForEntry}
       env={env}
       setEnv={setEnvPatch}

package/src/client/Inspector.tsx

@@ -432,6 +432,40 @@ function formatStateValue(value: unknown): string {
   return out.length > 80 ? `${out.slice(0, 80)}…` : out
 }
 
+/* ---------- Shared (ctxState) strip: editable, global across components ---------- */
+
+// Infer the editor from the live value's type — ctxState carries no control
+// metadata (it's a plain object, like the `state` declaration), so primitives
+// get a fitting inline editor and anything richer falls back to a read-only chip.
+function CtxStateEditor({ value, onChange }: { value: unknown; onChange: (next: unknown) => void }) {
+  if (typeof value === 'boolean') {
+    return <button type="button" role="switch" aria-checked={value} className={`wb-switch${value ? ' on' : ''}`} onClick={() => onChange(!value)} />
+  }
+  if (typeof value === 'number') {
+    return <input type="number" className="wb-ctxstate-input" value={Number.isFinite(value) ? value : ''} onChange={e => onChange(e.target.valueAsNumber)} />
+  }
+  if (typeof value === 'string') {
+    return <input type="text" className="wb-ctxstate-input" value={value} onChange={e => onChange(e.target.value)} />
+  }
+  return <span className="v">{formatStateValue(value)}</span>
+}
+
+function CtxStateStrip({ ctxState, setCtxStateValue }: { ctxState: Record<string, unknown>; setCtxStateValue: InspectorProps['setCtxStateValue'] }) {
+  const keys = Object.keys(ctxState)
+  if (!keys.length) return null
+  return (
+    <div className="wb-ctxstate" title="Shared state (ctx.ctxState) — global across components, editable here or from any component">
+      <span className="wb-state-label">shared</span>
+      {keys.map(k => (
+        <span className="wb-state-item" key={k}>
+          <span className="k">{k}</span>
+          <CtxStateEditor value={ctxState[k]} onChange={next => setCtxStateValue(k, next)} />
+        </span>
+      ))}
+    </div>
+  )
+}
+
 function LogsStrip({ logs, clearLogs }: { logs: InspectorProps['logs']; clearLogs: InspectorProps['clearLogs'] }) {
   const recent = logs.slice(-50)
   return (
@@ -478,6 +512,8 @@ export function Inspector(props: InspectorProps) {
     logs,
     clearLogs,
     state,
+    ctxState,
+    setCtxStateValue,
     contexts,
     env,
     setEnv,
@@ -562,6 +598,7 @@ export function Inspector(props: InspectorProps) {
           ))}
         </div>
       )}
+      <CtxStateStrip ctxState={ctxState} setCtxStateValue={setCtxStateValue} />
       <div className="wb-inspector-body">
         {tab === 'Controls' && (
           <ControlsTab

package/src/client/bridge.ts

@@ -25,6 +25,14 @@ export function useWindoBridge(iframeRef: RefObject<HTMLIFrameElement | null>):
   const [logs, setLogs] = useState<WindoLogRow[]>([])
   const [stateValues, setStateValues] = useState<Record<string, Record<string, unknown>>>({})
   const [actionDisabled, setActionDisabled] = useState<Record<string, Record<string, boolean>>>({})
+  // Shared state: `ctxStateDefaults` is the config seed (from the manifest);
+  // `ctxState` is the latest snapshot echoed after a component writes it.
+  const [ctxStateDefaults, setCtxStateDefaults] = useState<Record<string, unknown>>({})
+  const [ctxState, setCtxStateEcho] = useState<Record<string, unknown>>({})
+  // Latest colour scheme a component pushed via `ctx.toggleTheme`/`setColorScheme`
+  // (null until one does). Wrapped in a fresh object each echo so consumers re-fire
+  // even when the same scheme is pushed twice (e.g. after a manual revert between).
+  const [colorScheme, setColorSchemeEcho] = useState<{ value: 'light' | 'dark' } | null>(null)
   const seqRef = useRef(0)
 
   const post = useCallback(
@@ -54,6 +62,7 @@ export function useWindoBridge(iframeRef: RefObject<HTMLIFrameElement | null>):
         setGroups(msg.groups)
         setTags(msg.tags)
         setContexts(msg.contexts)
+        setCtxStateDefaults(msg.ctxState)
         break
       case 'describe':
         setDescribe({
@@ -82,6 +91,12 @@ export function useWindoBridge(iframeRef: RefObject<HTMLIFrameElement | null>):
         setStateValues(prev => ({ ...prev, [msg.id]: msg.state }))
         setActionDisabled(prev => ({ ...prev, [msg.id]: Object.fromEntries(msg.actions.map(a => [a.id, a.disabled])) }))
         break
+      case 'ctx-state':
+        setCtxStateEcho(msg.state)
+        break
+      case 'color-scheme':
+        setColorSchemeEcho({ value: msg.colorScheme })
+        break
       case 'render-error':
         setRenderError({ message: msg.message, stack: msg.stack })
         break
@@ -100,6 +115,8 @@ export function useWindoBridge(iframeRef: RefObject<HTMLIFrameElement | null>):
 
   const setEnv = useCallback((env: WindoEnvState) => post({ source: WINDO_MSG, dir: 'host', type: 'set-env', env }), [post])
 
+  const setCtxState = useCallback((state: Record<string, unknown>) => post({ source: WINDO_MSG, dir: 'host', type: 'set-ctx-state', state }), [post])
+
   const invokeAction = useCallback((id: string, actionId: string) => post({ source: WINDO_MSG, dir: 'host', type: 'invoke-action', id, actionId }), [post])
 
   const clearLogs = useCallback(() => setLogs([]), [])
@@ -119,9 +136,13 @@ export function useWindoBridge(iframeRef: RefObject<HTMLIFrameElement | null>):
     clearLogs,
     stateValues,
     actionDisabled,
+    ctxStateDefaults,
+    ctxState,
+    colorScheme,
     select,
     setProps,
     setEnv,
+    setCtxState,
     invokeAction,
   }
 }

package/src/client/chrome.css

@@ -21,6 +21,9 @@
   --accent-text: #ffffff;
   --accent-soft: color-mix(in srgb, var(--accent) 8%, transparent);
   --danger: #c0443c;
+  --success: #3c7a4a;
+  --warn: #99661c;
+  --deprecated: #a8433a;
   --surface: #ffffff;
   --shadow: 0 1px 2px rgba(16, 16, 18, 0.04), 0 8px 24px rgba(16, 16, 18, 0.06);
   --mono: "JetBrains Mono", ui-monospace, "SF Mono", Menlo, Consolas, monospace;
@@ -41,6 +44,10 @@
   --accent-ui: color-mix(in oklab, var(--accent) 35%, white);
   --accent-soft: color-mix(in srgb, var(--accent-ui) 14%, transparent);
   --danger: #e0837b;
+  --success: #84c896;
+  --warn: #dcb064;
+  --deprecated: #e6918a;
+  --accent-contrast: #111113;
   --surface: #161618;
   --shadow: 0 1px 2px rgba(0, 0, 0, 0.4), 0 10px 32px rgba(0, 0, 0, 0.45);
 }
@@ -373,7 +380,7 @@ button {
 
 [data-theme="dark"] .wb-tag-pill {
   background: var(--accent-ui);
-  color: #111113;
+  color: var(--accent-contrast);
 }
 
 .wb-tag-pill .x {
@@ -476,7 +483,7 @@ button {
 [data-theme="dark"] .wb-check.checked {
   background: var(--accent-ui);
   border-color: var(--accent-ui);
-  color: #111113;
+  color: var(--accent-contrast);
 }
 
 .wb-tag-divider {
@@ -642,29 +649,16 @@ button {
 }
 
 .wb-status.stable {
-  color: #3c7a4a;
-  background: rgba(60, 122, 74, 0.1);
+  color: var(--success);
+  background: color-mix(in srgb, var(--success) 10%, transparent);
 }
 .wb-status.beta {
-  color: #99661c;
-  background: rgba(153, 102, 28, 0.1);
+  color: var(--warn);
+  background: color-mix(in srgb, var(--warn) 10%, transparent);
 }
 .wb-status.deprecated {
-  color: #a8433a;
-  background: rgba(168, 67, 58, 0.1);
-}
-
-[data-theme="dark"] .wb-status.stable {
-  color: #84c896;
-  background: rgba(132, 200, 150, 0.12);
-}
-[data-theme="dark"] .wb-status.beta {
-  color: #dcb064;
-  background: rgba(220, 176, 100, 0.12);
-}
-[data-theme="dark"] .wb-status.deprecated {
-  color: #e6918a;
-  background: rgba(230, 145, 138, 0.12);
+  color: var(--deprecated);
+  background: color-mix(in srgb, var(--deprecated) 10%, transparent);
 }
 
 .wb-nav-empty {
@@ -768,7 +762,7 @@ button {
 [data-theme="dark"] .wb-trigger.on {
   background: var(--accent-ui);
   border-color: var(--accent-ui);
-  color: #111113;
+  color: var(--accent-contrast);
 }
 
 .wb-trigger .tdot {
@@ -1242,6 +1236,45 @@ button {
   font-weight: 600;
 }
 
+/* Editable shared-state strip (ctx.ctxState) — same look as .wb-state, with inline editors */
+
+.wb-ctxstate {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+  padding: 7px 16px;
+  border-bottom: 1px solid var(--border);
+  background: var(--inset);
+  font-size: 11.5px;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  flex-shrink: 0;
+}
+
+.wb-ctxstate .wb-state-item {
+  gap: 6px;
+}
+
+.wb-ctxstate-input {
+  width: 90px;
+  padding: 1px 6px;
+  border: 1px solid var(--border);
+  border-radius: 5px;
+  background: var(--bg);
+  color: var(--text);
+  font: inherit;
+  font-weight: 600;
+}
+
+.wb-ctxstate-input[type='number'] {
+  width: 60px;
+}
+
+.wb-ctxstate-input:focus {
+  outline: none;
+  border-color: var(--accent-ui);
+}
+
 .wb-tab {
   height: 100%;
   padding: 0 1px;
@@ -1359,7 +1392,7 @@ button {
 [data-theme="dark"] .wb-save {
   background: var(--accent-ui);
   border-color: var(--accent-ui);
-  color: #111113;
+  color: var(--accent-contrast);
 }
 
 .wb-save:disabled {
@@ -1401,8 +1434,8 @@ button {
   font-size: 10.5px;
   line-height: 1.6;
   color: var(--danger);
-  background: rgba(192, 68, 60, 0.07);
-  border: 1px solid rgba(192, 68, 60, 0.25);
+  background: color-mix(in srgb, var(--danger) 7%, transparent);
+  border: 1px solid color-mix(in srgb, var(--danger) 25%, transparent);
   border-radius: var(--r);
   padding: 8px 10px;
   white-space: pre-wrap;
@@ -1411,11 +1444,7 @@ button {
 .wb-saved-flash {
   font-size: 11.5px;
   font-weight: 550;
-  color: #3c7a4a;
-}
-
-[data-theme="dark"] .wb-saved-flash {
-  color: #84c896;
+  color: var(--success);
 }
 
 .wb-schema {
@@ -1632,11 +1661,7 @@ button {
   color: var(--text);
 }
 .wb-copy.copied {
-  color: #3c7a4a;
-}
-
-[data-theme="dark"] .wb-copy.copied {
-  color: #84c896;
+  color: var(--success);
 }
 
 /* ---------- Variants gallery ---------- */
@@ -1885,6 +1910,10 @@ select.wb-ctrl-input {
   background-position: right 8px center;
 }
 
+[data-theme="dark"] select.wb-ctrl-input {
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='12' viewBox='0 0 24 24' fill='none' stroke='%239b9ba2' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpolyline points='6 9 12 15 18 9'/%3E%3C/svg%3E");
+}
+
 .wb-ctrl-row input[type="range"] {
   flex: 1;
   accent-color: var(--accent-ui);
@@ -1935,7 +1964,7 @@ select.wb-ctrl-input {
 }
 
 [data-theme="dark"] .wb-switch.on::after {
-  background: #111113;
+  background: var(--accent-contrast);
 }
 
 .wb-context-empty {
@@ -2050,21 +2079,17 @@ select.wb-ctrl-input {
   color: var(--accent-ui);
 }
 .wb-log.warn .llevel {
-  color: #99661c;
+  color: var(--warn);
 }
 .wb-log.error .llevel {
   color: var(--danger);
 }
 
-[data-theme="dark"] .wb-log.warn .llevel {
-  color: #dcb064;
-}
-
 .wb-log.warn {
-  background: rgba(153, 102, 28, 0.05);
+  background: color-mix(in srgb, var(--warn) 5%, transparent);
 }
 .wb-log.error {
-  background: rgba(192, 68, 60, 0.05);
+  background: color-mix(in srgb, var(--danger) 5%, transparent);
 }
 
 .wb-log .lmsg {
@@ -2098,8 +2123,8 @@ select.wb-ctrl-input {
   margin: 14px 16px;
   padding: 12px 14px;
   border-radius: 10px;
-  background: rgba(192, 68, 60, 0.07);
-  border: 1px solid rgba(192, 68, 60, 0.25);
+  background: color-mix(in srgb, var(--danger) 7%, transparent);
+  border: 1px solid color-mix(in srgb, var(--danger) 25%, transparent);
 }
 
 .wb-render-error .rtitle {
@@ -2147,8 +2172,8 @@ select.wb-ctrl-input {
   margin: 12px 16px 0 16px;
   padding: 8px 11px;
   border-radius: var(--r);
-  background: rgba(168, 67, 58, 0.06);
-  border: 1px solid rgba(168, 67, 58, 0.22);
+  background: color-mix(in srgb, var(--deprecated) 6%, transparent);
+  border: 1px solid color-mix(in srgb, var(--deprecated) 22%, transparent);
   color: var(--danger);
   font-size: 12px;
   line-height: 1.45;

package/src/client/internal-types.ts

@@ -45,10 +45,18 @@ export interface BridgeApi {
   stateValues: Record<string, Record<string, unknown>>
   /** Live `disabled` flag per action id (keyed windo id → action id), echoed from the preview. */
   actionDisabled: Record<string, Record<string, boolean>>
+  /** Config seed for the shared `ctxState` (from the manifest) — fills keys the chrome hasn't persisted. */
+  ctxStateDefaults: Record<string, unknown>
+  /** Latest shared-state snapshot echoed after a component wrote it via `ctx.setCtxState`. */
+  ctxState: Record<string, unknown>
+  /** Latest colour scheme a component pushed via `ctx.toggleTheme`/`setColorScheme` (null until one does). Re-wrapped each echo so repeated same-value pushes still propagate. */
+  colorScheme: { value: 'light' | 'dark' } | null
   // outbound
   select: (id: string) => void
   setProps: (id: string, json: string) => void
   setEnv: (env: WindoEnvState) => void
+  /** Push the shared state down to the preview (editor edit or reload re-sync). */
+  setCtxState: (state: Record<string, unknown>) => void
   invokeAction: (id: string, actionId: string) => void
 }
 
@@ -146,6 +154,10 @@ export interface InspectorProps {
   clearLogs: () => void
   /** Live component-local state snapshot for the selected windo (drives the read-only State strip). */
   state: Record<string, unknown>
+  /** Shared, cross-component state — drives the editable Shared strip. */
+  ctxState: Record<string, unknown>
+  /** Edit one key of the shared state (pushes down to the preview). */
+  setCtxStateValue: (key: string, value: unknown) => void
   /** Context metadata filtered to this windo (its `uses` providers + all ambient). */
   contexts: WindoContextMeta[]
   env: ChromeEnv

package/src/index.ts

@@ -14,6 +14,7 @@ export {
   WINDO_MSG,
 } from './protocol'
 export type {
+  Ctxual,
   WindoAction,
   WindoActionMeta,
   WindoActionTrigger,
@@ -34,6 +35,7 @@ export type {
   WindoFactoryArg,
   WindoFieldError,
   WindoGroup,
+  WindoInitContext,
   WindoLogEntry,
   WindoLogger,
   WindoManifestEntry,