@westonkd/sprint 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Weston Dransfield
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,146 @@
+# Sprint
+
+A React component library for products that people and AI agents both use. Sprint components
+look and behave like any other interface, and can describe themselves to an agent on request.
+
+Status: experimental. A full catalog of components on top of the agent runtime, verified in jsdom
+and normal browsers; no real WebMCP implementation has accepted a descriptor yet.
+
+## What a Sprint component does
+
+- **Two views, one component.** Humans see the rendered interface; agents switch the same
+  component to a minimal text view, with no second implementation behind it.
+- **Names you can rely on.** A `div` tells an agent nothing; every Sprint component publishes
+  its identity, parts, and current state as attributes it promises not to rename.
+- **Actions, not clicks.** In Chrome 149 a component registers what it can do with the browser,
+  so an agent calls the action instead of aiming a click at it.
+
+```tsx
+<Button tone="action" block onClick={prepare}>Prepare launch</Button>
+```
+
+A person sees a flat acid action bar. Flip the containing provider to agent view and the same
+component renders as text, with no HTML elements at all:
+
+```
+- **Button** "Prepare launch" [block, tone=action] → tool `press-prepare-launch`
+```
+
+Both renderings are built from one `AgentNode` created during the same render, so they cannot
+disagree. The tool name comes from the button's own label. Nothing here is written by hand, and
+switching views does not unmount anything: `press-prepare-launch` stays registered in both.
+
+```tsx
+<SprintProvider view={agentMode ? "agent" : "human"}>
+```
+
+An agent with WebMCP can flip it itself by calling `set-page-view`.
+
+## If you are an agent
+
+Everything on the published site is there for you to read directly. Start with the manifest.
+
+- [`agent-manifest.json`](https://westonkd.github.io/sprint/agent-manifest.json) — every
+  component, what it is for, when not to use it, and the tools it registers.
+- [`llms.txt`](https://westonkd.github.io/sprint/llms.txt) — the same catalogue as plain text,
+  in one request.
+- [`components/Button.md`](https://westonkd.github.io/sprint/components/Button.md) — one
+  Markdown page per component, if you only need one.
+- [The workbench as text](https://westonkd.github.io/sprint/workbench.html#/?view=agent) — any
+  documentation page, rendered as the text you would read.
+
+In Chrome 149 the components on the site also register their actions as WebMCP tools, so you
+can call them rather than click them.
+
+## Requirements
+
+Docker with Compose v2. Nothing else, everything runs in containers.
+
+## Getting started
+
+```bash
+docker compose watch dev
+```
+
+Use `watch` rather than `up`. Compose syncs your edits into the container as you save them; plain
+`up` serves the snapshot baked into the image.
+
+The workbench serves on http://localhost:5173. It is the documentation. Component pages are
+generated entirely from `agent-manifest.json` — props, state attributes, tool descriptors, and every
+code snippet come from the same metadata an agent reads. Each example can be toggled between the
+human and agent view, individually or a whole page at once.
+
+Four written guides sit alongside them:
+
+- **WebMCP** — the platform API: both forms, availability, hard limits, and security.
+- **Integration philosophy** — the decisions behind how Sprint uses it, and what each costs.
+- **Composing a page** — Shell, PageHeader, Panel, and Stack, top down.
+- **Composing a form** — fields, tool naming, and the submit lifecycle.
+
+```bash
+docker compose run --rm verify
+```
+
+Runs typecheck, lint, tests, and the library build.
+
+```bash
+docker compose run --rm format
+```
+
+Applies Biome's safe fixes, formatting, and import sorting in place.
+
+## Layout
+
+```
+src/
+  agent/
+    attributes.ts   the data-sprint* contract
+    registry.ts     component metadata, manifest assembly
+    view/           agent view: DOM serializer and Markdown formatter
+    webmcp/         the single document.modelContext call site, plus useAgentTool
+  components/       one directory each, see Button for the reference shape
+  provider/         SprintProvider, AgentRegion, page-level read tools
+  styles/           token primitives, semantic roles, base resets
+  test/             Vitest setup and the WebMCP test double
+dev/                local workbench, not published
+scripts/            manifest generation, build output checks
+```
+
+## Consuming it
+
+React 19 and TypeScript, no runtime dependencies. Not published to npm yet. Once it is, the
+package name is `@westonkd/sprint`:
+
+```tsx
+import { Button, SprintProvider } from "@westonkd/sprint";
+import "@westonkd/sprint/styles.css";
+```
+
+```ts
+import manifest from "@westonkd/sprint/agent-manifest.json" with { type: "json" };
+```
+
+Wrap your app in `SprintProvider` to register the page-level `list-page-regions` and `read-region`
+tools. Components work without it.
+
+## WebMCP
+
+Tools use the [web platform WebMCP API](https://developer.chrome.com/docs/ai/webmcp)
+(`document.modelContext`), which currently ships in Chrome 149 behind an origin trial or
+`chrome://flags/#enable-webmcp-testing`. Everywhere else, registration is a no-op and the components
+work normally — the agent view does not depend on it.
+
+## Documentation
+
+The site is published at [westonkd.github.io/sprint](https://westonkd.github.io/sprint/): a
+landing page, the workbench with live documentation for every component, and the agent surfaces
+listed above.
+
+- [AGENTS.md](AGENTS.md) — contribution workflow and the agent contract.
+- `.claude/skills/sprint/references/PRD.md` — what this is and why.
+- `.claude/skills/sprint/references/DESIGN.md` — the visual language.
+- `.claude/skills/sprint/references/ADR/` — why it is built this way.
+
+## License
+
+[MIT](LICENSE)