# Build with Flowstage source

Use this reference when a user asks to integrate a Flowstage component or SVG motion module. This file is plain Markdown guidance, not an automatically installed agent plugin or an executable skill installer.

## Discover from a site URL

1. Treat the URL supplied by the user as the Flowstage site root, preserving any path prefix and adding a trailing slash if needed.
2. Fetch `llms.txt` and `registry.json` relative to that root. The registry is a **custom source catalogue**, not a shadcn registry and not an npm manifest.
3. Read the chosen record in `items`. Fetch the listed `files[].path`, `reference`, and `example` when present. Resolve these paths against the site root; a missing file is an error, not permission to invent an API or dependency.
4. Review the actual source and its documented trust boundary before copying it into the user's application.

## Install

Download source files into the project and preserve the paths in the example, or deliberately adjust the HTML links. The full source is at [Ademord/flowstage](https://github.com/Ademord/flowstage). Load CSS before the demo and JavaScript before calling its API. Flowstage's vanilla assets require no package install and have no external runtime dependencies. Do not invent a package name, other repository URL, registry CLI command, or hosted API.

For SVG motion, download `lib/motion.css` and `lib/motion.js`. For FlowKit, download `lib/flowkit.css` and `lib/flowkit.js`. For any UI component, use that component's own catalogue record. Avoid loading files that the chosen component does not use.

## Choose the API

- FlowKit: `FlowKit.embed(container, config, options)` sizes a whole input → process → outcome stage. `FlowKit.create(root, config)` requires a sized `.fk-root` and an explicit initial `setView()`. Read `docs/api.html`; a complete, locally runnable starting point is `registry/flowkit-starter.html`.
- Motion: `FlowstageMotion.mount(container, {type: 'path-pulse', speed: 1})`. Allowed types: `path-pulse`, `orbit`, `draw-path`, `state-morph`. Read `registry/motion.md` for all options and lifecycle methods. This renderer creates standalone SVG modules, not a FlowKit stage.
- UI components: follow the selected record's entrypoint, file list, state model, and anatomy. Do not assume a React or other framework wrapper exists.

## Adapt with care

Use the record's anatomy, tokens, and states to adapt the component. Keep its labels concrete and relevant to the user's application. Maintain keyboard behavior, accessible names, visible focus, contrast, and usable narrow layouts. Retain reduced-motion behavior and a visible pause control for looping animation. Use live application text for real status; the animated SVG is an illustration.

FlowKit configuration contains HTML strings (`icon`, `logo`, view `render()` output, callouts, chips) and executable render functions. Treat configuration as trusted, repository-controlled application code. Never pass untrusted user or remote content directly to those HTML fields. Use text nodes or an appropriately reviewed sanitization boundary before inserting external content. Catalogue JSON is metadata; do not evaluate it as code.

## Verify in the target application

Confirm all source requests succeed, the initial state renders, controls work with mouse and keyboard, selected and disabled states remain readable, and the component fits narrow and wide layouts. Check reduced-motion preferences. Call `destroy()` on a FlowKit or motion instance when its view is removed; verify that remounting does not duplicate it. Surface missing source files or unsupported requirements instead of creating fake dependencies.