AGENTS.md@src/widgets/source git:20261026.274ed78A

Immutable. This exact content never changes and is served at /api/v1/blob/8c226ecaa938888f.

# widgets/source — the docs previews' source files and Run

## Purpose

Kobra's source panel for every docs preview: what the preview is made of,
as files a reader reads, edits, copies, downloads and runs in the page —
a real tool, never a mock.

## Ownership

- `SourcePanel.vue` — the panel: file tabs, the toolbar (Revert, Copy,
  Download all as a zip, Run), the editor, Run's problems, a status line.
- `Editor.vue` — a textarea with a line gutter (native undo, IME, screen
  readers); Tab / Shift+Tab indent the selected lines, Escape hands the
  next Tab back to the page (never a keyboard trap), Enter keeps the
  indent, ⌘/Ctrl+Enter runs; the gutter follows the textarea's scroll.
- `RunView.vue` — a run's component inside an error boundary: what it
  throws shows in the preview, not as a broken page.
- `model/files.ts` — pure: the kit index as export → file, a snippet's kind,
  a fragment completed into an SFC (`asSfc`), the kit files an example
  imports per framework, file names, `prompt.md`.
- `model/compile.ts` — pure: Vue's compiler-sfc (browser build) for SFCs;
  TypeScript removed by cutting its type syntax (enums, namespaces and
  parameter properties are refused with their place — they need a
  transpiler); imports/exports linked into a function body evaluated with
  the page's modules; scoped styles, CSS Modules (`$style` names renamed),
  tokens scoped to one preview (`scopeTokens`).
- `model/run.ts` — the linker: the page's Vue (an explicit API list, not a
  namespace — a namespace import keeps all of Vue in every page's chunk),
  the kit's packages (`PACKAGES`), `@stylexjs/stylex`, and the kit.
- `model/stylex.ts` — StyleX at run time, standing in for its bundler
  plugin: `create`, `attrs` (Vue), `props`, `defineVars`, `keyframes`,
  `firstThatWorks`. Every property and condition becomes one atomic class
  (`x` + a hash of its rule) written once into `style[data-run-stylex]` in
  the head (`plain`, then `conditional`: pseudo-classes and pseudo-elements
  join the selector, at-rules wrap it); the last style to set a property
  wins; numbers are px except the unitless properties.

## Local Contracts

- Mounted by `pages/docs/DemoCard.vue` (lazy, on the Code tab's first open,
  then kept so edits survive the Preview tab) with the authored snippet,
  `docsCode` as `translate`, the framework, the styling system and the
  card's `SourceContext` (section, place, title, line, URL, install steps).
- Files: the example (`<Section>Example.vue|.svelte`, a fragment completed
  with its imports and template, in the reader's framework and styling
  system; non-component snippets keep their language: `.sh`, `.ts`,
  `.css`), the kit's own source for each kit export it imports, the kit's
  tokens (`engine/theme.css`) and `prompt.md`. Kit files are the repo's,
  served by the build at `kit/src/<vue|svelte>/` with a recursive
  `files.json` listing (`kitSources` in `rstack.config.ts`) — never a copy
  kept by hand. `KIT_INDEX` names each kit's public entry (the Vue kit's
  `tailwind/index.ts`); `kitIndex` maps its exports to files relative to
  it and `resolveKitFile` resolves a kit import against its importer's
  folder, across layers. Zip paths mirror the install: the example and
  prompt at the root, kit files under `dither-kit/` (`dither-kit-svelte/`)
  in their layer folders.
- Edits are kept per file (the example's per framework and styling
  system); a tab marks an edited file; Revert restores the original.
- Run (Vue, in any styling system: Tailwind, CSS, CSS Modules, and StyleX
  through `model/stylex.ts`; Svelte says why not):
  an example that edits only itself links to the page's kit (the very
  modules the docs run on). Once a kit file is edited, the example links to
  a kit evaluated from its source — the edits and every kit file the run
  reaches — so a compound component and its contexts (chart, series,
  field, drawer) share one set of modules. Problems come back located
  (`file line:col`, a click opens the file at the place); the last good run
  stays up. The result replaces the demo in the preview (shown above the
  source while it runs) until "Restore the demo"; its CSS lives in one
  `<style>` per card; edited tokens apply to that preview only.
- New kit imports from `vue` or a package must be linkable: the spec holds
  `VUE`/`PACKAGES` to every name the kit and its compiled templates import.
- Sounds (`shared/lib/sound.ts`): tab and toolbar taps, copy.

## Verification

- `tests/source.spec.ts` (run against compiler-sfc's browser build, the one
  Run ships: `define.test` aliases it, since the node target would take the
  CJS build and its uninstalled template engines): the kit index, snippet kinds, `asSfc`, kit files
  per framework, names and the prompt; TypeScript stripping and refusals,
  linking (re-exports, live bindings, missing exports), SFC styles and
  located errors, scoped tokens; every kit file compiles and links, and
  every name it imports is provided; the zip read back entry by entry
  (CRC-32 included); the sound cues and the mute; the StyleX runtime
  (atomic classes, last style wins, conditions after plain rules,
  variables, keyframes, fallbacks); a DemoCard opened to its files, an
  example edited and run, a kit file edited and run, a broken edit located,
  the demo restored, and the example run as StyleX (its elements carry the
  runtime's classes, their rules in the head).
- Browser walk (`rs dev`): `/docs/switch` and `/docs/button` — tabs by
  keyboard, edit and Run, a kit file edited (`DitherSwitch.vue`), tokens
  edited (`theme.css`), CSS, CSS Modules and StyleX runs, the Svelte
  refusal, the zip (`unzip -t`), copy; `/docs/area` — the `…` sketch
  located, data filled in, `Area.vue` edited and the chart drawn; a 390px
  phone and light theme.

## Child DOX Index

- none