@andersseen/skills 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Andersseen
+
+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,72 @@
+# @andersseen/skills
+
+Installable **AI agent skills** for the Andersseen ecosystem — one focused skill
+per library, plus an orchestrator that routes between them. Works with any agent
+that reads `.claude/skills/` (Claude Code, and compatible tools).
+
+Each skill teaches an agent how to use **one** library correctly (real package
+names, verified APIs, no invented props), so you can install only what your
+project needs.
+
+## Quick start
+
+```bash
+# Interactive: pick skills, then choose install or download
+npx @andersseen/skills
+
+# Install everything (orchestrator + all libraries)
+npx @andersseen/skills add --all
+
+# Add just what you need
+npx @andersseen/skills add andersseen web-components icon
+```
+
+`pnpm dlx @andersseen/skills …` and `yarn dlx @andersseen/skills …` work too.
+
+## The two modes
+
+| Mode         | Command flag        | Destination            | Use when                              |
+| ------------ | ------------------- | ---------------------- | ------------------------------------- |
+| **Install**  | _(default)_         | `./.claude/skills/`    | Activate immediately for your agent   |
+| **Download** | `--download` / `-d` | `./andersseen-skills/` | Review the SKILL.md before activating |
+
+## Available skills
+
+| Skill                       | Alias            | Library                           |
+| --------------------------- | ---------------- | --------------------------------- |
+| `andersseen`                | `orchestrator`   | Ecosystem router (start here)     |
+| `andersseen-web-components` | `web-components` | `@andersseen/web-components`      |
+| `andersseen-headless-core`  | `headless-core`  | `@andersseen/headless-components` |
+| `andersseen-icon`           | `icon`           | `@andersseen/icon`                |
+| `andersseen-motion`         | `motion`         | `@andersseen/motion`              |
+| `andersseen-layout`         | `layout`         | `@andersseen/layout`              |
+
+```bash
+npx @andersseen/skills list   # print the same table with descriptions
+```
+
+## Commands
+
+```
+npx @andersseen/skills                       Interactive picker
+npx @andersseen/skills list                  List available skills
+npx @andersseen/skills add <name...>         Install into ./.claude/skills/
+npx @andersseen/skills add --all             Install every skill
+npx @andersseen/skills add <name> --download Download into ./andersseen-skills/
+
+Options: -d/--download  -a/--all  -f/--force  -h/--help
+```
+
+Names accept the full folder name (`andersseen-web-components`) or the short
+alias (`web-components`). `all` selects everything.
+
+## Recommended: start with the orchestrator
+
+Install `andersseen` alongside the per-library skills. It decides **which**
+library fits a task and defers to the focused skill — so the agent reaches for
+the right package instead of guessing.
+
+```bash
+npx @andersseen/skills add andersseen web-components headless-core icon motion layout
+# ≡ npx @andersseen/skills add --all
+```

package/bin/cli.mjs

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+// @andersseen/skills — install focused AI agent skills into a consumer project.
+//
+// Two modes, mirroring the two things a dev actually wants:
+//   install  → copies the skill into ./.claude/skills/<name>/ (agent picks it up)
+//   download → copies the skill into ./andersseen-skills/<name>/ (review first)
+//
+// Zero runtime dependencies: Node built-ins only, so `npx @andersseen/skills`
+// works offline once the package is fetched.
+
+import { readdir, readFile, mkdir, cp } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve } from 'node:path';
+import { createInterface } from 'node:readline';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SKILLS_DIR = resolve(HERE, '..', 'skills');
+const INSTALL_DIR = resolve(process.cwd(), '.claude', 'skills');
+const DOWNLOAD_DIR = resolve(process.cwd(), 'andersseen-skills');
+
+const c = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+};
+const paint = (color, s) => (process.stdout.isTTY ? `${c[color]}${s}${c.reset}` : s);
+
+/** Read every skill folder that has a SKILL.md, with its description. */
+async function discoverSkills() {
+  if (!existsSync(SKILLS_DIR)) return [];
+  const entries = await readdir(SKILLS_DIR, { withFileTypes: true });
+  const skills = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const skillMd = join(SKILLS_DIR, entry.name, 'SKILL.md');
+    if (!existsSync(skillMd)) continue;
+    const raw = await readFile(skillMd, 'utf8');
+    skills.push({
+      name: entry.name,
+      alias: entry.name.replace(/^andersseen-/, ''),
+      description: frontmatterDescription(raw),
+      dir: join(SKILLS_DIR, entry.name),
+      orchestrator: entry.name === 'andersseen',
+    });
+  }
+  // Orchestrator first, then alphabetical.
+  return skills.sort((a, b) => Number(b.orchestrator) - Number(a.orchestrator) || a.name.localeCompare(b.name));
+}
+
+function frontmatterDescription(raw) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(raw);
+  if (!match) return '';
+  const body = match[1];
+  const line = /description:\s*(?:'([^']*)'|"([^"]*)"|(.*))/.exec(body);
+  if (!line) return '';
+  return (line[1] ?? line[2] ?? line[3] ?? '').replace(/\s+/g, ' ').trim();
+}
+
+/** Resolve user tokens (folder name, alias, or "all") to skill objects. */
+function resolveSelection(tokens, skills) {
+  const wanted = new Set();
+  const unknown = [];
+  for (const tokenRaw of tokens) {
+    const token = tokenRaw.toLowerCase();
+    if (token === 'all' || token === '*') {
+      skills.forEach(s => wanted.add(s.name));
+      continue;
+    }
+    const hit = skills.find(s => s.name === token || s.alias === token);
+    if (hit) wanted.add(hit.name);
+    else unknown.push(tokenRaw);
+  }
+  return { selected: skills.filter(s => wanted.has(s.name)), unknown };
+}
+
+async function place(skill, mode, force) {
+  const root = mode === 'download' ? DOWNLOAD_DIR : INSTALL_DIR;
+  const target = join(root, skill.name);
+  if (existsSync(target) && !force) {
+    console.log(
+      `  ${paint('yellow', '•')} ${skill.name} ${paint('dim', 'already exists (skipped — pass --force to overwrite)')}`,
+    );
+    return 'skipped';
+  }
+  await mkdir(root, { recursive: true });
+  await cp(skill.dir, target, { recursive: true, force: true });
+  const shown = mode === 'download' ? join('andersseen-skills', skill.name) : join('.claude', 'skills', skill.name);
+  console.log(`  ${paint('green', '✓')} ${skill.name} ${paint('dim', '→ ' + shown)}`);
+  return 'written';
+}
+
+function printSkillList(skills) {
+  const pad = Math.max(...skills.map(s => s.name.length));
+  for (const s of skills) {
+    const tag = s.orchestrator ? paint('cyan', ' [orchestrator]') : '';
+    console.log(`  ${paint('bold', s.name.padEnd(pad))}${tag}`);
+    if (s.description) {
+      const short = s.description.length > 96 ? s.description.slice(0, 93) + '…' : s.description;
+      console.log(`  ${paint('dim', ' '.repeat(pad) + '  ' + short)}`);
+    }
+  }
+}
+
+function help() {
+  console.log(`
+${paint('bold', '@andersseen/skills')} — install AI agent skills for the Andersseen ecosystem
+
+${paint('bold', 'Usage')}
+  npx @andersseen/skills                      ${paint('dim', 'interactive picker (choose skills + install/download)')}
+  npx @andersseen/skills list                 ${paint('dim', 'list available skills')}
+  npx @andersseen/skills add <name...>        ${paint('dim', 'install into ./.claude/skills/')}
+  npx @andersseen/skills add --all            ${paint('dim', 'install every skill')}
+  npx @andersseen/skills add <name> --download ${paint('dim', 'download into ./andersseen-skills/ (review first)')}
+
+${paint('bold', 'Options')}
+  -d, --download        Download only — do not activate in .claude/skills
+  -a, --all             Select every skill
+  -f, --force           Overwrite an existing skill folder
+  -h, --help            Show this help
+
+${paint('bold', 'Names')} accept the folder name or its short alias, e.g.
+  andersseen-web-components  ${paint('dim', '≡')}  web-components
+  andersseen                 ${paint('dim', '≡')}  orchestrator ("andersseen" routes to the right skill)
+
+${paint('bold', 'Examples')}
+  npx @andersseen/skills add andersseen web-components icon
+  pnpm dlx @andersseen/skills add --all
+  yarn dlx @andersseen/skills add layout --download
+`);
+}
+
+function ask(rl, question) {
+  return new Promise(res => rl.question(question, a => res(a.trim())));
+}
+
+async function interactive(skills) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    console.log(paint('bold', '\nAndersseen agent skills\n'));
+    skills.forEach((s, i) => {
+      const tag = s.orchestrator ? paint('cyan', ' [orchestrator]') : '';
+      console.log(`  ${paint('bold', String(i + 1).padStart(2))}. ${s.name}${tag}`);
+      if (s.description) {
+        const short = s.description.length > 88 ? s.description.slice(0, 85) + '…' : s.description;
+        console.log(`      ${paint('dim', short)}`);
+      }
+    });
+    console.log(`\n  ${paint('dim', "Enter numbers (e.g. 1,3), a name, or 'all'.")}`);
+    const pick = await ask(rl, paint('cyan', '\nSkills to add: '));
+    let selected;
+    if (/^(all|\*)$/i.test(pick.trim())) {
+      selected = skills.slice();
+    } else {
+      const byIndex = pick
+        .split(/[,\s]+/)
+        .filter(Boolean)
+        .map(t => (/^\d+$/.test(t) ? skills[Number(t) - 1]?.name : t))
+        .filter(Boolean);
+      selected = resolveSelection(byIndex, skills).selected;
+    }
+    if (selected.length === 0) {
+      console.log(paint('yellow', '\nNothing selected. Bye.'));
+      return 0;
+    }
+
+    console.log(
+      `\n  ${paint('bold', '1')}. Install  ${paint('dim', '→ ./.claude/skills/  (your agent uses it immediately)')}`,
+    );
+    console.log(
+      `  ${paint('bold', '2')}. Download ${paint('dim', '→ ./andersseen-skills/  (review before activating)')}`,
+    );
+    const action = await ask(rl, paint('cyan', '\nChoose 1 or 2 [1]: '));
+    const mode = action.trim() === '2' || /^d/i.test(action.trim()) ? 'download' : 'install';
+
+    console.log('');
+    for (const skill of selected) await place(skill, mode, false);
+    printDone(mode, selected);
+    return 0;
+  } finally {
+    rl.close();
+  }
+}
+
+function printDone(mode, selected) {
+  console.log('');
+  if (mode === 'install') {
+    console.log(paint('green', `Installed ${selected.length} skill(s) into .claude/skills/.`));
+    console.log(paint('dim', 'Restart your agent (or reload skills) to pick them up.'));
+  } else {
+    console.log(paint('green', `Downloaded ${selected.length} skill(s) into andersseen-skills/.`));
+    console.log(paint('dim', 'Move the folders into .claude/skills/ when you are ready to activate them.'));
+  }
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (argv.includes('-h') || argv.includes('--help')) return help();
+
+  const skills = await discoverSkills();
+  if (skills.length === 0) {
+    console.error(paint('red', 'No skills bundled with this package.'));
+    process.exitCode = 1;
+    return;
+  }
+
+  const command = argv[0];
+
+  if (command === 'list' || command === 'ls') {
+    console.log(paint('bold', '\nAvailable skills\n'));
+    printSkillList(skills);
+    console.log('');
+    return;
+  }
+
+  if (command === undefined) return interactive(skills);
+
+  if (command === 'add' || command === 'install' || command === 'i') {
+    const rest = argv.slice(1);
+    const download = rest.includes('-d') || rest.includes('--download');
+    const all = rest.includes('-a') || rest.includes('--all');
+    const force = rest.includes('-f') || rest.includes('--force');
+    const names = rest.filter(a => !a.startsWith('-'));
+    const mode = download ? 'download' : 'install';
+
+    let selected;
+    if (all) {
+      selected = skills.slice();
+    } else {
+      if (names.length === 0) {
+        console.error(paint('red', 'Specify at least one skill name, or use --all.'));
+        console.error(paint('dim', 'Run `npx @andersseen/skills list` to see the options.'));
+        process.exitCode = 1;
+        return;
+      }
+      const { selected: sel, unknown } = resolveSelection(names, skills);
+      if (unknown.length) {
+        console.error(paint('red', `Unknown skill(s): ${unknown.join(', ')}`));
+        console.error(paint('dim', 'Run `npx @andersseen/skills list` to see the options.'));
+        process.exitCode = 1;
+        return;
+      }
+      selected = sel;
+    }
+
+    console.log('');
+    for (const skill of selected) await place(skill, mode, force);
+    printDone(mode, selected);
+    return;
+  }
+
+  console.error(paint('red', `Unknown command: ${command}`));
+  help();
+  process.exitCode = 1;
+}
+
+main().catch(err => {
+  console.error(paint('red', 'Error: ' + (err?.message ?? String(err))));
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@andersseen/skills",
+  "version": "0.0.1",
+  "description": "Installable AI agent skills (Claude Code, Cursor, ...) for the Andersseen ecosystem. One focused skill per library, plus an orchestrator.",
+  "type": "module",
+  "bin": {
+    "andersseen-skills": "bin/cli.mjs",
+    "and-skills": "bin/cli.mjs"
+  },
+  "files": [
+    "bin",
+    "skills",
+    "README.md"
+  ],
+  "keywords": [
+    "claude-code",
+    "agent-skills",
+    "cursor",
+    "web-components",
+    "andersseen",
+    "ai"
+  ],
+  "author": "Andersseen",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Andersseen/and-web-components.git",
+    "directory": "packages/skills"
+  },
+  "scripts": {
+    "lint": "node bin/cli.mjs list >/dev/null",
+    "format": "prettier --write \"**/*.{md,mjs,json}\"",
+    "format:check": "prettier --check \"**/*.{md,mjs,json}\""
+  }
+}

package/skills/andersseen/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: andersseen
+description:
+  'Orchestrator for the Andersseen front-end ecosystem. Use this to decide WHICH
+  Andersseen library to reach for and route to its focused skill before writing
+  code. Trigger phrases: andersseen, @andersseen, and-* component, andersseen
+  design system, which andersseen package, build a UI with andersseen, headless
+  logic, icon, motion animation, layout attributes. Routes to:
+  andersseen-web-components, andersseen-headless-core, andersseen-icon,
+  andersseen-motion, andersseen-layout.'
+---
+
+# Andersseen — ecosystem orchestrator
+
+You are working in a project that uses the **Andersseen** front-end ecosystem: a
+set of small, framework-agnostic libraries that compose. Your job in this skill
+is to **pick the right library for the task and defer to its focused skill**
+instead of guessing an API.
+
+Each library is documented by a dedicated skill (one library, one skill). Load
+the matching skill's guidance before generating code for that library. If a
+sibling skill is not installed, tell the user how to add it (see _Install_).
+
+## Routing table — task → library → skill
+
+| The user wants to…                                            | Library                           | Skill                       |
+| ------------------------------------------------------------- | --------------------------------- | --------------------------- |
+| Drop styled, ready-made UI (`<and-button>`, `<and-modal>`, …) | `@andersseen/web-components`      | `andersseen-web-components` |
+| Build a **custom** UI but reuse state/a11y/keyboard logic     | `@andersseen/headless-components` | `andersseen-headless-core`  |
+| Render or register SVG icons (`<and-icon>`, `getIcon`)        | `@andersseen/icon`                | `andersseen-icon`           |
+| Animate on scroll/hover/tap via HTML attributes               | `@andersseen/motion`              | `andersseen-motion`         |
+| Compose layout & typography with `and-layout` / `and-text`    | `@andersseen/layout`              | `andersseen-layout`         |
+
+## How the layers relate
+
+```
+headless-core   →  pure TS state machines + ARIA + keyboard (no DOM, no CSS)
+     ↓
+web-components  →  Stencil custom elements (Shadow DOM) built ON headless-core + icon
+```
+
+`icon`, `motion`, and `layout` are independent satellites usable from any
+framework or from plain HTML.
+
+## Decision guide
+
+1. **Need a component that already exists?** (button, card, modal, tabs, drawer,
+   navbar, select, input…) → use `web-components`. Do **not** re-implement it
+   with headless-core.
+2. **Building something the library doesn't ship, but that needs correct
+   open/close, focus, keyboard, or ARIA?** → use `headless-core` and provide
+   your own markup/styles.
+3. **Just icons?** → `icon`. Remember `registerIcons(COMPONENT_ICONS)` is
+   required whenever `web-components` is used.
+4. **Just motion/entrance animation?** → `motion` (attribute-driven, respects
+   `prefers-reduced-motion`).
+5. **Just layout/spacing/typography without a utility framework?** → `layout`.
+
+You can combine several — e.g. `web-components` + `icon` + `motion`. When you
+do, follow each library's own skill rules; never invent props, classes, or
+attributes that a skill does not document.
+
+## Global rules for every Andersseen library
+
+- Use the **real package names** exactly: `@andersseen/web-components`,
+  `@andersseen/headless-components`, `@andersseen/icon`, `@andersseen/motion`,
+  `@andersseen/layout`.
+- Only use public props, slots, events, attributes, and exported functions that
+  the relevant skill documents. Never target internal Shadow DOM parts.
+- Prefer design-token CSS variables over hardcoded colors.
+- Clean up: call the `cleanup()`/`destroy()` handles that a library returns when
+  unmounting SPA views.
+
+## Install
+
+Skills are distributed via the `@andersseen/skills` CLI:
+
+```bash
+# install the orchestrator + everything
+npx @andersseen/skills add --all
+
+# or add just the ones you need
+npx @andersseen/skills add andersseen web-components icon
+
+# download to ./andersseen-skills/ to review before activating
+npx @andersseen/skills add layout --download
+```
+
+Runtime packages install normally, e.g.:
+
+```bash
+npm i @andersseen/web-components @andersseen/icon
+```

package/skills/andersseen-headless-core/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: andersseen-headless-core
+description:
+  'Reuse Andersseen headless behavior primitives
+  (@andersseen/headless-components) for state, accessibility, and keyboard logic
+  when building a CUSTOM UI. Load when you need correct open/close, focus, ARIA,
+  or keyboard handling without a pre-styled component: createTabs,
+  createDropdown, createModal, createTooltip, createToastManager,
+  createAccordion, createDrawer, createNavbar, createSidebar. Trigger phrases:
+  headless, state machine, a11y logic, keyboard navigation, ARIA props, custom
+  component behavior.'
+---
+
+# @andersseen/headless-components — headless behavior primitives
+
+Framework-agnostic headless primitives for behavior, a11y, and keyboard
+navigation. **No DOM rendering, no CSS, no framework lock-in.** You provide
+markup/styles; the library provides state + ARIA + interaction logic. Reach for
+this when the pre-built `@andersseen/web-components` element does not fit and
+you must build custom markup that still behaves correctly.
+
+## Install
+
+```bash
+npm i @andersseen/headless-components
+```
+
+## Verified module exports
+
+```
+@andersseen/headless-components
+@andersseen/headless-components/button
+@andersseen/headless-components/accordion
+@andersseen/headless-components/tabs
+@andersseen/headless-components/dropdown
+@andersseen/headless-components/modal
+@andersseen/headless-components/tooltip
+@andersseen/headless-components/toast
+@andersseen/headless-components/drawer
+@andersseen/headless-components/alert
+@andersseen/headless-components/navbar
+@andersseen/headless-components/sidebar
+@andersseen/headless-components/breadcrumb
+@andersseen/headless-components/menu-list
+@andersseen/headless-components/context-menu
+```
+
+## Canonical API contract
+
+Most modules follow:
+
+```ts
+const logic = createX(config);
+
+logic.state; // read-only state snapshot
+logic.actions; // imperative updates
+logic.queries; // derived state (where available)
+logic.get*Props(...); // ARIA/data attributes for semantic elements
+logic.handle*KeyDown(...); // keyboard support
+```
+
+## Verified factories
+
+`createButton`, `createAccordion`, `createTabs`, `createDropdown`,
+`createModal`, `createTooltip`, `createDrawer`, `createAlert`, `createNavbar`,
+`createSidebar`, `createBreadcrumb`, `createMenuList`, `createContextMenu`, and
+`createToastManager` (**not** `createToast`).
+
+## Core usage examples
+
+### Tabs
+
+```ts
+import { createTabs } from '@andersseen/headless-components/tabs';
+
+const tabs = createTabs({
+  defaultValue: 'overview',
+  orientation: 'horizontal',
+  activationMode: 'automatic',
+  onValueChange: tabId => console.log(tabId),
+});
+
+const listProps = tabs.getTabListProps();
+const triggerProps = tabs.getTabTriggerProps('overview');
+const panelProps = tabs.getTabContentProps('overview');
+
+tabs.handleTabKeyDown(event, 'overview', ['overview', 'settings']);
+```
+
+### Dropdown
+
+```ts
+import { createDropdown } from '@andersseen/headless-components/dropdown';
+
+const dropdown = createDropdown({
+  defaultOpen: false,
+  closeOnSelect: true,
+  placement: 'bottom',
+  onOpenChange: open => console.log(open),
+});
+
+const triggerProps = dropdown.getTriggerProps();
+const menuProps = dropdown.getMenuProps();
+const itemProps = dropdown.getItemProps('theme-light');
+
+dropdown.handleTriggerKeyDown(event);
+dropdown.handleMenuKeyDown(event, ['theme-light', 'theme-dark']);
+```
+
+### Modal
+
+```ts
+import { createModal } from '@andersseen/headless-components/modal';
+
+const modal = createModal({
+  closeOnEscape: true,
+  closeOnOverlayClick: true,
+  onOpenChange: open => console.log(open),
+});
+
+modal.actions.open();
+const overlayProps = modal.getOverlayProps();
+const contentProps = modal.getContentProps();
+const closeBtnProps = modal.getCloseButtonProps();
+
+window.addEventListener('keydown', modal.handleKeyDown);
+```
+
+### Tooltip
+
+```ts
+import { createTooltip } from '@andersseen/headless-components/tooltip';
+
+const tooltip = createTooltip({
+  placement: 'top',
+  openDelay: 120,
+  closeDelay: 80,
+  onVisibilityChange: visible => console.log(visible),
+});
+
+trigger.addEventListener('mouseenter', tooltip.handleMouseEnter);
+trigger.addEventListener('mouseleave', tooltip.handleMouseLeave);
+trigger.addEventListener('focusin', tooltip.handleFocusIn);
+trigger.addEventListener('focusout', tooltip.handleFocusOut);
+
+const triggerProps = tooltip.getTriggerProps();
+const tooltipProps = tooltip.getTooltipProps();
+```
+
+### Toast manager
+
+```ts
+import { createToastManager } from '@andersseen/headless-components/toast';
+
+const toasts = createToastManager({
+  defaultDuration: 3000,
+  maxToasts: 5,
+  position: 'bottom-right',
+  onToastsChange: list => console.log(list),
+});
+
+const id = toasts.actions.present('Saved', 'success');
+toasts.actions.dismiss(id);
+toasts.actions.dismissAll();
+
+const containerProps = toasts.getContainerProps();
+const dismissProps = toasts.getDismissProps();
+```
+
+## Rules
+
+- Use the real package name: `@andersseen/headless-components`.
+- Do not invent rendering helpers; compose with semantic HTML and spread the
+  returned props objects onto your elements.
+- Preserve the provided keyboard handlers and ARIA attributes — do not
+  re-implement focus/state logic already provided by `actions`/`queries`.
+- Call `destroy()` where provided (tooltip / toast manager) during unmount
+  cleanup.