AGENTS.md@src/widgets/source · diff
git:20261023.ce23847 to git:20261023.e8a097c
3 added, 1 removed. Audit A to A.
# 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`), and the kit.
## 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 (`theme.css`) and `prompt.md`. Kit files are the repo's, served by
the build at `kit/src/<vue|svelte>/` with a `files.json` listing
(`kitSources` in `rstack.config.ts`) — never a copy kept by hand. Zip
paths mirror the install: the example and prompt at the root, kit files
under `dither-kit/` (`dither-kit-svelte/`).
- 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, Tailwind/CSS/CSS Modules; Svelte and StyleX say 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`: the kit index, snippet kinds, `asSfc`, kit files
+ - `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; a DemoCard opened to its
files, an example edited and run, a kit file edited and run, a broken
edit located, the demo restored.
- 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 and CSS Modules runs, StyleX and Svelte
refusals, 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