@vielzeug/codex 26.10.15 → 26.10.16

package/data/search.json

@@ -183,6 +183,36 @@
     "slug": "assay",
     "source": "export { walkflattree } from './dom';\nexport { assayerror, assayqueryerror, assaytimeouterror } from './errors';\nexport {\n  dispatch,\n  fireblur,\n  firechange,\n  fireclick,\n  firecustom,\n  firefocus,\n  fireinput,\n  firekeydown,\n  firekeyup,\n  firesubmit,\n} from './events';\nexport { installforminternalspolyfill } from './form internals';\nexport { getslotted, type queryscope, queryallinshadow, queryinshadow, querypart, within } from './query';\nexport {\n  type delayoptions,\n  delay,\n  type eventuallyoptions,\n  eventually,\n  type waitoptions,\n  waitforevent,\n  waituntil,\n} from './wait';\n"
   },
+  {
+    "category": "ui interaction",
+    "description": "guided onboarding and contextual product tours for web applications",
+    "docs": {
+      "index": "   \ntitle: 'beacon: product tours and coachmarks'\ndescription: \"guided onboarding and contextual product tours for web applications\"\npackage: beacon\ncategory: ui interaction\nkeywords: [onboarding, product tour, coachmark, walkthrough, step by step, spotlight, headless]\nrelated: [refine, orbit, ripple, vault]\nexports: [createtour, createcoachmark, resolvetarget]\nenvironments: [browser]\n   \n\n<!   markdownlint disable md025 md033 md060   >\n\n<packagehero package=\"beacon\" />\n\n## why beacon?\n\nproduct tours rot fast: hand wired step sequences hard code positioning, persistence, and target waiting into application code, and break the first time the ui moves. beacon is the headless half of a tour — it owns step order, target waiting, resumable progress, and events — while your markup (or `@vielzeug/refine`'s `ore tour` components) decides what a step looks like.\n\n```ts\n// before: step logic tangled with rendering and storage\nlet step = number(localstorage.getitem('tour step') ?? 0);\nfunction showstep() {\n  const el = document.queryselector(steps[step].selector);\n  card.style.top = `${el.getboundingclientrect().bottom + 8}px`; // breaks on scroll\n  card.innerhtml = steps[step].html;\n}\n\n// after: the engine owns order, persistence, and the anchor rect\nimport { createtour } from '@vielzeug/beacon';\n\nconst tour = createtour({ id: 'welcome', steps, storage });\ntour.current.subscribe(() => rendercard(tour.current.value)); // rect is the live anchor\ntour.start();\n```\n\n| feature | beacon | shepherd.js | intro.js |\n|     |     |     |     |\n| bundle size | <packageinfo package=\"beacon\" type=\"size\" /> | ~50 kb | ~25 kb |\n| external dependencies | <ore icon name=\"check\" size=\"16\"></ore icon> (none) | <ore icon name=\"check\" size=\"16\"></ore icon> | <ore icon name=\"check\" size=\"16\"></ore icon> |\n| headless (you own the ui) | <ore icon name=\"check\" size=\"16\"></ore icon> | <ore icon name=\"x\" size=\"16\"></ore icon> | <ore icon name=\"x\" size=\"16\"></ore icon> |\n| resumable persisted progress | <ore icon name=\"check\" size=\"16\"></ore icon> | <ore icon name=\"check\" size=\"16\"></ore icon> | <ore icon name=\"triangle alert\" size=\"16\"></ore icon> |\n| versioned re offers | <ore icon name=\"check\" size=\"16\"></ore icon> | <ore icon name=\"x\" size=\"16\"></ore icon> | <ore icon name=\"x\" size=\"16\"></ore icon> |\n| coachmarks (single hints) | <ore icon name=\"check\" size=\"16\"></ore icon> | <ore icon name=\"x\" size=\"16\"></ore icon> | <ore icon name=\"triangle alert\" size=\"16\"></ore icon> |\n\n<div class=\"decision callout\">\n\n**use beacon when** tours must survive ui changes: steps anchor to your real dom, progress persists and resumes, and the card markup is yours (or refine's ready made `ore tour`).\n\n**consider shepherd or intro.js when** you want a fully rendered, opinionated tour widget you never style yourself and can accept their dom and css.\n\n</div>\n\n## installation\n\n::: code group\n\n```sh [pnpm]\npnpm add @vielzeug/beacon\n```\n\n```sh [npm]\nnpm install @vielzeug/beacon\n```\n\n```sh [yarn]\nyarn add @vielzeug/beacon\n```\n\n:::\n\n## quick start\n\ndefine the tour as data, run it, and render the current step wherever you like. the handle is disposable, so component teardown cleans everything up.\n\n```ts\nimport { createtour, type beacontourconfig } from '@vielzeug/beacon';\n\nconst config = {\n  id: 'getting started',\n  steps: [\n    { id: 'welcome', title: 'welcome', description: 'a two minute look around.' },\n    { id: 'nav', target: '[data tour=\"nav\"]', title: 'navigation', placement: 'bottom start' },\n  ],\n} satisfies beacontourconfig;\n\nconst tour = createtour(config);\n\n// render from the live snapshot: rect is the anchor, null centers the card.\nconst unsubscribe = tour.current.subscribe(() => {\n  const { presentation, rect, step } = tour.current.value;\n  console.log({ presentation, rect, step }); // drive your card from this\n});\n\ntour.start();\n\n// on teardown:\nunsubscribe();\ntour.dispose();\n```\n\n## features\n\n<div class=\"features grid\">\n\n  `createtour()` runs a sequential, resumable walkthrough over your own dom.\n  `createcoachmark()` shows a single contextual hint once per user per version.\n  `current` is a live `readable<beaconcurrentstep>` snapshot: step, index, placement, presentation, and resolved anchor rect, kept fresh on scroll, resize, and layout changes.\n  `target` accepts a selector, `element`, rect, or lazy resolver, and beacon waits for lazily mounted targets before showing the step.\n  `storage` persists progress through any `beaconstorage` bridge (localstorage, indexeddb via `@vielzeug/vault`, a server api).\n  `version` re offers a finished tour when the product changes underneath it.\n  `tap()` subscribes to lifecycle events (`step:start`, `tour:complete`, `target missing`, ...) with `abortsignal` support.\n  `resolvetarget()` turns any target into a viewport rect compatible with `@vielzeug/orbit` positioners.\n  `ore tour`'s `bind()` in `@vielzeug/refine` renders a handle and routes its actions with zero glue code.\n\n</div>\n\n## documentation\n\n<div class=\"doc links\">\n\n  [usage guide](./usage.md)\n  [api reference](./api.md)\n  [examples](./examples.md)\n  [migration guide](./migration.md)\n\n</div>\n\n## see also\n\n<div class=\"see also\">\n\n  [refine](/refine/): ships `ore tour` and `ore spotlight`, the ready made dialog/popover/bottom sheet presentation layer for a beacon handle.\n  [orbit](/orbit/): compute exact popover coordinates from `current.rect` when you build a custom presentation.\n  [vault](/vault/): durable storage backends that plug into `beaconstorage` with a six line bridge.\n  [ripple](/ripple/): the `readable` signals every beacon handle exposes come from here.\n\n</div>\n\n<!   markdownlint enable md025 md033 md060   >\n",
+      "api": "   \ntitle: 'beacon: api reference'\ndescription: public api of @vielzeug/beacon.\n   \n\n[[toc]]\n\n## api overview\n\n| symbol | purpose | execution mode | common gotcha |\n|     |     |     |     |\n| `createtour(config)` | runs a sequential, resumable walkthrough over the app's dom | sync (storage reads may be async) | `start()` is a no op when the stored record says the tour is completed |\n| `createcoachmark(config)` | shows a single contextual hint anchored to one target | sync (storage reads may be async) | `show()` is a no op after `dismiss()` until `reset()` or a `version` bump |\n| `resolvetarget(target)` | resolves any target to a viewport space rect or `null` | sync | call it per position update; a scrolled target's rect changes |\n| `beaconerror` | base class for all beacon originated errors | — | catch this to catch any beacon error |\n| `beaconconfigerror` | invalid tour/coachmark configuration | thrown at creation | empty `steps` or duplicate step ids fail at `createtour()` |\n| `beacondisposederror` | handle used after `dispose()` | thrown on call | `dispose()` is idempotent; later method calls throw |\n\n## package entry point\n\n| import | purpose |\n|     |     |\n| `@vielzeug/beacon` | complete public beacon api |\n\n   \n\n## core functions\n\n### createtour\n\n```ts\nfunction createtour(config: beacontourconfig): beacontourhandle\n```\n\nreturns a live handle for one guided tour. throws `beaconconfigerror` when `id` is empty, `steps` is empty, or step ids are duplicated.\n\nparameters: see [`beacontourconfig`](#beacontourconfig).\n\n**returns:** a [`beacontourhandle`](#beacontourhandle) that is also `disposable`.\n\n**example:**\n\n```ts\nimport { createtour } from '@vielzeug/beacon';\n\nconst tour = createtour({\n  id: 'release tour',\n  steps: [{ id: 'intro', title: 'what changed' }],\n  autostart: true,\n});\n\ntour.status.subscribe(() => console.log(tour.status.value));\n```\n\nhandle methods:\n\n| member | behavior |\n|     |     |\n| `start()` | begin or resume the tour. no op when completed; throws after dispose. |\n| `next()` | advance; past the last step, finishes the tour. |\n| `back()` | return to the previous step. no op on the first step. |\n| `goto(step)` | jump to a step by index or id. unknown values warn and no op. |\n| `pause()` | stop showing, keep progress so `start()` resumes it. |\n| `skip()` | end from a \"skip\" control. persisted as dismissed, reported with reason `'skip'`. |\n| `finish()` | mark finished and stop showing. |\n| `dismiss()` | end by closing (escape, backdrop). persisted as dismissed. |\n| `reset()` | discard persisted progress; the tour is eligible again. |\n| `tap(handler, options?)` | observe [`beacontourevent`](#beacontourentype)s; returns an unsubscribe, honors `options.signal`. |\n| `dispose()` / `[symbol.dispose]()` | release all listeners and observers. idempotent. |\nhandle properties:\n\n| member | type | notes |\n|     |     |     |\n| `current` | `readable<beaconcurrentstep>` | the snapshot to render; `step` is `null` while closed. beacon re publishes the rect on scroll, resize, and target layout changes while a step is active. |\n| `status` | `readable<beaconstatus>` | lifecycle, persisted on every change. |\n| `eligible` | `readable<boolean>` | whether the tour should be offered to this user. |\n| `steps` | `readonly beaconstep[]` | the configured steps, in order. |\n| `id` | `string` | the configured id (also the storage key suffix). |\n| `disposed` | `boolean` | whether `dispose()` has run. |\n| `disposalsignal` | `abortsignal` | aborted on dispose; pass it to your own listeners. |\n\n   \n\n### createcoachmark\n\n```ts\nfunction createcoachmark(config: beaconcoachmarkconfig): beaconcoachmarkhandle\n```\n\nreturns a handle for one contextual hint. throws `beaconconfigerror` when `id` is empty.\n\nparameters: see [`beaconcoachmarkconfig`](#beaconcoachmarkconfig).\n\n**returns:** a [`beaconcoachmarkhandle`](#beaconcoachmarkhandle) that is also `disposable`.\n\n**example:**\n\n```ts\nimport { createcoachmark } from '@vielzeug/beacon';\n\nconst hint = createcoachmark({\n  id: 'share hint',\n  target: '[data tour=\"share\"]',\n  title: 'share this board',\n});\n\nhint.show(); // waits for the target to mount if it is not on screen yet\n```\n\nhandle members:\n\n| member | behavior |\n|     |     |\n| `show()` | show the hint. no op once dismissed without a newer version. |\n| `hide()` | hide without recording it as seen; it can show again. |\n| `dismiss()` | hide and record as seen permanently (until `reset()`/`version`). |\n| `reset()` | discard the persisted record; the hint is eligible again. |\n| `tap(handler, options?)` | observe `coachmark:show`, `coachmark:dismiss`, and common events. |\n| `current` | `readable<beaconcurrentstep>` — the hint as a single step snapshot: `step` is the hint while visible, `null` while hidden. the rect stays live on scroll, resize, and target layout changes. |\n| `eligible` | `readable<boolean>` — never seen, or superseded by a newer version. |\n\n   \n\n### resolvetarget\n\n```ts\nfunction resolvetarget(target: beacontarget): beaconrect | null\n```\n\nresolves a target to a viewport space rect, or `null` when it is not available yet. strings resolve through `document.queryselector`; functions are called and their result normalized.\n\n| parameter | type | description |\n|     |     |     |\n| `target` | `beacontarget` | selector, `element`, rect, or lazy resolver. |\n\n**returns:** `beaconrect | null` — shape compatible with `getboundingclientrect()` and `@vielzeug/orbit`'s `rect`.\n\n**example:**\n\n```ts\nimport { resolvetarget } from '@vielzeug/beacon';\n\nconst rect = resolvetarget('[data tour=\"share\"]');\n// anchor an orbit positioner from a virtual reference:\nconst reference = { getboundingclientrect: () => resolvetarget('[data tour=\"share\"]') ?? zero_rect };\n```\n\n   \n\n## types\n\n### beacontourconfig\n\n| option | type | default | description |\n|     |     |     |     |\n| `id` | `string` | required | unique identity; used as the storage key. |\n| `steps` | `readonly beaconstep[]` | required | every step, in order. at least one. |\n| `autoscroll` | `boolean` | `true` | scroll each anchored step's target into view when it activates. |\n| `autostart` | `boolean` | `false` | start on the next microtask when eligible. |\n| `placement` | `beaconplacement` | `'auto'` | default placement handed to the presentation layer. |\n| `presentation` | `beaconpresentation` | `'auto'` | default presentation handed to the presentation layer. |\n| `scrolloffset` | `number \\| (() => number)` | `0` | pixels kept clear at the viewport top for a sticky header, read at scroll time. |\n| `storage` | `beaconstorage` | memory only | progress persistence. |\n| `targettimeoutms` | `number` | `infinity` | how long to wait for a step's target before skipping that step. `0` publishes immediately with a `null` rect. |\n| `version` | `number` | `1` | bump to re show a finished tour. |\n\n### beaconcoachmarkconfig\n\n| option | type | default | description |\n|     |     |     |     |\n| `id` | `string` | required | unique identity; used as the storage key. |\n| `target` | `beacontarget` | required | where the hint points. |\n| `autoshow` | `boolean` | `true` | show automatically when not yet seen. |\n| `data` | `unknown` | — | free form data for the presentation layer. |\n| `description` | `string` | — | supporting copy. |\n| `placement` | `beaconplacement` | `'auto'` | preferred side. |\n| `presentation` | `beaconpresentation` | `'auto'` | preferred presentation. |\n| `storage` | `beaconstorage` | memory only | seen record persistence. |\n| `title` | `string` | — | headline copy. |\n| `version` | `number` | `1` | bump to re show a seen coachmark. |\n\n### beaconstep\n\n```ts\ninterface beaconstep {\n  readonly data?: unknown;\n  readonly description?: string;\n  readonly id: string;\n  readonly placement?: beaconplacement;\n  readonly presentation?: beaconpresentation;\n  readonly target?: beacontarget;\n  readonly title?: string;\n}\n```\n\none stop in a tour. `id` is stable and persisted — renaming it resets progress for that step. omit `target` for a centered intro/outro step. `placement`/`presentation` override the tour level defaults.\n\n### beacontarget\n\n```ts\ntype beacontarget = beacontargetresolver | beaconrect | element | string;\n```\n\nwhat a step points at. selectors and elements anchor to real dom; rects (or resolvers returning one) anchor to element less geometry such as a canvas region.\n\n### beacontargetresolver\n\n```ts\ntype beacontargetresolver = () => element | beaconrect | null;\n```\n\nresolves a target lazily; `null` means \"not available yet\".\n\n### beaconrect\n\n```ts\ninterface beaconrect {\n  readonly height: number;\n  readonly width: number;\n  readonly x: number;\n  readonly y: number;\n}\n```\n\na viewport space rectangle in css pixels. matches `@vielzeug/orbit`'s `rect` shape.\n\n### beaconplacement\n\n```ts\ntype beaconplacement =\n  | 'auto'\n  | 'bottom' | 'bottom end' | 'bottom start'\n  | 'left' | 'left end' | 'left start'\n  | 'right' | 'right end' | 'right start'\n  | 'top' | 'top end' | 'top start';\n```\n\npreferred side for an anchored presentation; `'auto'` asks the positioning layer to choose.\n\n### beaconpresentation\n\n```ts\ntype beaconpresentation = 'auto' | 'bottom sheet' | 'modal' | 'popover';\n```\n\nhow a step should be presented. `'auto'` lets the presentation layer pick by available space.\n\n### beaconstatus\n\n```ts\ntype beaconstatus = 'active' | 'completed' | 'dismissed' | 'idle' | 'paused';\n```\n\ntour lifecycle, persisted across visits. `'idle'` means never started.\n\n### beaconprogress\n\n```ts\ninterface beaconprogress {\n  readonly status: beaconstatus;\n  readonly stepindex: number;\n  readonly version: number;\n}\n```\n\nthe persisted record for one tour or coachmark. `stepindex` is ` 1` before the first step. records are validated on read; invalid records fall back to a fresh tour.\n\n### beaconstorage\n\n```ts\ninterface beaconstorage {\n  get(key: string): promise<beaconprogress | null | undefined> | beaconprogress | null | undefined;\n  remove(key: string): promise<unknown> | unknown;\n  set(key: string, value: beaconprogress): promise<unknown> | unknown;\n}\n```\n\nminimal storage contract; sync or async. values are json. keys arrive namespaced (`@vielzeug/beacon:<id>`). a `@vielzeug/vault` store plugs in with:\n\n```ts\nconst storage: beaconstorage = {\n  get: (key) => store.get('progress', key),\n  remove: (key) => store.delete('progress', key),\n  set: (key, value) => store.put('progress', { id: key, ...value }),\n};\n```\n\n### beaconcurrentstep\n\n```ts\ninterface beaconcurrentstep {\n  readonly placement: beaconplacement;\n  readonly presentation: beaconpresentation;\n  readonly rect: beaconrect | null;\n  readonly step: beaconstep | null;\n  readonly stepindex: number;\n  readonly totalsteps: number;\n}\n```\n\nthe snapshot a presentation layer renders from. `step` is `null` before start and after the tour ends; `rect` is `null` for centered steps and unresolved targets. while a step is active, beacon keeps `rect` fresh on scroll, resize, and target layout changes — no app side refresh call is needed.\n\n### beacontourevent\n\n```ts\ntype beacontourevent =\n  | { readonly index: number; readonly step: beaconstep; readonly type: 'step:start' }\n  | { readonly index: number; readonly step: beaconstep; readonly type: 'step:complete' }\n  | { readonly reason: 'finish' | 'skip'; readonly type: 'tour:complete' }\n  | { readonly type: 'tour:dismiss' }\n  | { readonly status: beaconstatus; readonly type: 'status change' }\n  | { readonly message: string; readonly type: 'target missing' }\n  | { readonly index: number; readonly message: string; readonly step: beaconstep; readonly type: 'target waiting' }\n  | { readonly error: unknown; readonly message: string; readonly type: 'warning' }\n  | { readonly type: 'dispose' };\n```\n\nnotable moments a tour reports through `tap()`. `target missing` means a step was skipped because its target did not appear in time; `target waiting` fires when a step begins waiting for its target to mount; `warning` carries storage or handler failures.\n\n### beaconcoachmarkevent\n\n```ts\ntype beaconcoachmarkevent =\n  | { readonly type: 'coachmark:show' }\n  | { readonly type: 'coachmark:dismiss' }\n  | { readonly type: 'target waiting' }\n  | { readonly error: unknown; readonly message: string; readonly type: 'warning' }\n  | { readonly type: 'dispose' };\n```\n\nnotable moments a coachmark reports through `tap()`.\n\n### beacontourhandle / beaconcoachmarkhandle\n\nthe objects returned by `createtour()` and `createcoachmark()`, documented in [core functions](#core functions). both expose `disposalsignal`, `disposed`, `tap()`, `dispose()`, and `[symbol.dispose]()`.\n\n## errors\n\n| error | triggered by | notes |\n|     |     |     |\n| `beaconerror` | base for all beacon errors | `name` is the subclass name; `cause` supported via `erroroptions`. |\n| `beaconconfigerror` | empty `id`, empty `steps`, missing/duplicate step ids | thrown synchronously from `createtour()`/`createcoachmark()`. |\n| `beacondisposederror` | calling handle methods after `dispose()` | `dispose()` itself never throws. |\n",
+      "usage": "   \ntitle: 'beacon: usage guide'\ndescription: how to use @vielzeug/beacon.\n   \n\n[[toc]]\n\n## basic usage\n\na tour is a config object plus a handle you drive from your own ui. the handle never renders anything: it publishes a `current` snapshot, and your card (or refine's `ore tour`) renders it.\n\n```ts\nimport { createtour } from '@vielzeug/beacon';\n\nconst tour = createtour({\n  id: 'product tour',\n  steps: [\n    { id: 'welcome', title: 'welcome', description: 'see what changed in this release.' },\n    { id: 'nav', target: '[data tour=\"nav\"]', title: 'find everything', placement: 'bottom start' },\n    { id: 'share', target: '[data tour=\"share\"]', title: 'share the board', placement: 'bottom end' },\n  ],\n  autostart: true,\n});\n\n// readable<t> from @vielzeug/ripple: the listener takes no arguments;\n// read .value inside it.\nconst unsubscribe = tour.current.subscribe(() => {\n  const current = tour.current.value;\n  if (!current.step) {\n    hidecard();\n    return;\n  }\n  rendercard({\n    anchor: current.rect, // viewport rect of the target, null for centered steps\n    index: current.stepindex,\n    placement: current.placement,\n    presentation: current.presentation,\n    title: current.step.title,\n    total: current.totalsteps,\n  });\n});\n\n// wire your card's controls back to the handle.\ncardel.addeventlistener('next', () => tour.next());\ncardel.addeventlistener('back', () => tour.back());\ncardel.addeventlistener('skip', () => tour.skip());\n\n// on teardown:\nunsubscribe();\ntour.dispose();\n```\n\n`start()` is a no op when the stored record says this user already completed the tour, so calling it on every page load is safe.\n\n## steps and targets\n\na step without a `target` centers (intro/outro copy). a step with one anchors, and beacon waits for the target to exist before publishing the step — a tour can walk through lazily mounted routes without any coordination code.\n\n```ts\nconst tour = createtour({\n  id: 'deep tour',\n  steps: [\n    // selector: resolved with document.queryselector on activation.\n    { id: 'sidebar', target: '[data tour=\"sidebar\"]', title: 'your libraries' },\n    // element: a ref your framework already holds.\n    { id: 'editor', target: editorel, title: 'the editor' },\n    // rect: geometry with no element, such as a canvas region.\n    { id: 'chart', target: { height: 120, width: 240, x: 400, y: 300 }, title: 'this trend' },\n    // resolver: computed on every activation, and on scroll/resize while the step is active.\n    { id: 'selection', target: () => window.getselection()?.getrangeat(0).getboundingclientrect() ?? null, title: 'your selection' },\n  ],\n  // give up waiting after 4s and skip the step instead of hanging the tour.\n  targettimeoutms: 4000,\n});\n```\n\nwith the default `targettimeoutms: infinity`, a step whose target never mounts simply waits: the tour resumes the moment the user navigates to it. set `0` to publish immediately with a `null` rect instead of waiting.\n\n## persisting progress\n\nwithout `storage`, progress lives in memory for the handle's lifetime only. any object matching `beaconstorage` makes it durable — values are json, keys are namespaced under `@vielzeug/beacon:`.\n\n```ts\nimport type { beaconstorage } from '@vielzeug/beacon';\n\nconst storage: beaconstorage = {\n  get: (key) => json.parse(localstorage.getitem(key) ?? 'null'),\n  remove: (key) => localstorage.removeitem(key),\n  set: (key, value) => localstorage.setitem(key, json.stringify(value)),\n};\n\nconst tour = createtour({ id: 'product tour', steps, storage });\n```\n\nasync storage works too: `get` may return a promise, and the tour boots as soon as it resolves. a `set` that rejects is reported through `tap()` as a `warning` event, never thrown.\n\nrecords are validated on read, so a hand edited or stale record falls back to a fresh tour instead of crashing.\n\n### re offering a finished tour\n\nbump `version` when the product changes and every user who finished the old tour becomes eligible again — users mid tour on the old version keep their progress.\n\n```ts\nconst tour = createtour({\n  id: 'product tour',\n  steps: newsteps,\n  version: 2, // stored records at version 1 no longer block the tour\n});\n```\n\n`reset()` clears the persisted record for the current user, which is what a \"replay tour\" or \"reset onboarding\" control should call before `start()`.\n\n## driving a refine presentation\n\n`@vielzeug/refine` ships `ore tour` (a dialog with step footer, progress, and focus handling) and `ore spotlight` (a decorative cutout that dims everything but the target). a beacon handle satisfies `ore tour`'s `tourcontroller` shape, so one call wires both directions:\n\n```ts\nimport type { oretourelement } from '@vielzeug/refine/tour';\n\nconst card = document.queryselector<oretourelement>('#tour card');\n\nconst tour = createtour({ id: 'product tour', presentation: 'auto', steps });\n\n// bind() renders `current` into the card's props and routes the card's\n// next/back/skip/finish/dismiss actions back into the handle.\nconst unbind = card.bind(tour);\n\ntour.start();\n\n// on teardown:\nunbind();\ntour.dispose();\n```\n\n`presentation: 'auto'` maps to a popover on wide viewports and a bottom sheet on narrow ones; ore tour makes that switch itself and freezes the choice while the card is open, so a mid step resize never rebuilds the card. beacon keeps `current.rect` fresh on scroll, resize, and layout changes, so the anchored card follows the layout with no app side listeners.\n\napps that render their own markup read `current` directly instead (see [basic usage](#basic usage)).\n\n## coachmarks\n\na coachmark is one hint anchored to one target, shown the first time the target appears and dismissed permanently after. use it for the \"explain this button once\" moment a tour would be too heavy for — or as the follow up a tour hands off to.\n\n```ts\nimport { createcoachmark } from '@vielzeug/beacon';\n\nconst share = createcoachmark({\n  id: 'share hint',\n  target: '[data tour=\"share\"]',\n  title: 'share this board',\n  description: 'send a link that opens straight into this view.',\n  storage,\n});\n\n// render from `current` — the same single step snapshot a tour publishes.\nshare.current.subscribe(() => console.log(share.current.value.step !== null, share.current.value.rect));\n\n// the target may never appear on this page; show() waits for it.\nshare.show();\n\n// \"got it\" button:\nshare.dismiss(); // records it as seen; never shows again for this version\n```\n\n`hide()` closes the hint without recording it, so it can appear again later; `dismiss()` is permanent until `reset()` or a `version` bump.\n\n## events and analytics\n\n`tap()` observes everything the engine considers notable. it returns an unsubscribe function and accepts an `abortsignal`, so one controller can tear down every subscription.\n\n```ts\nconst controller = new abortcontroller();\n\ntour.tap((event) => {\n  switch (event.type) {\n    case 'step:start':\n      analytics.track('tour_step', { id: tour.id, step: event.step.id });\n      break;\n    case 'tour:complete':\n      analytics.track('tour_complete', { id: tour.id, reason: event.reason });\n      break;\n    case 'target missing':\n      // a step's target never mounted: your selector drifted from the dom.\n      console.warn(event.message);\n      break;\n    case 'warning':\n      console.warn(event.message, event.error);\n      break;\n  }\n}, { signal: controller.signal });\n```\n\n`target missing` is the event to alert on: it means a step was skipped because its target did not appear within `targettimeoutms`, which is exactly how stale tours announce themselves.\n\n## testing\n\nbeacon runs without a rendering layer, so plain dom tests are enough. the default in memory storage keeps each handle's progress isolated, and `jsdom`'s `getboundingclientrect()` returns zero sized rects, which is fine for step order assertions.\n\n```ts\nimport { createtour } from '@vielzeug/beacon';\nimport { expect, test } from 'vitest';\n\ntest('walks steps in order and completes', () => {\n  const tour = createtour({\n    id: 'test tour',\n    steps: [{ id: 'a' }, { id: 'b' }],\n    targettimeoutms: 0, // publish immediately even without targets\n  });\n\n  tour.start();\n  expect(tour.current.value.step?.id).tobe('a');\n\n  tour.next();\n  expect(tour.current.value.step?.id).tobe('b');\n\n  tour.next(); // past the last step finishes\n  expect(tour.status.value).tobe('completed');\n});\n```\n\nfor persistence assertions, pass a `map` backed `beaconstorage` and a second handle with the same `id` to check it resumes where the first stopped.\n\n## framework integration\n\nbeacon is framework neutral: bridge the `readable` snapshot with whatever primitive your framework already has.\n\n::: code group\n\n```tsx [react]\nimport { useeffect, usestate } from 'react';\nimport { createtour } from '@vielzeug/beacon';\n\nfunction usetourstate(tour: returntype<typeof createtour>) {\n  const [current, setcurrent] = usestate(tour.current.value);\n  useeffect(() => tour.current.subscribe(() => setcurrent(tour.current.value)), [tour]);\n  return current;\n}\n```\n\n```vue [vue 3]\n<script setup lang=\"ts\">\nimport { onscopedispose, shallowref } from 'vue';\nimport { createtour } from '@vielzeug/beacon';\n\nconst current = shallowref(tour.current.value);\nconst unsubscribe = tour.current.subscribe(() => (current.value = tour.current.value));\nonscopedispose(unsubscribe);\n</script>\n```\n\n```svelte [svelte]\n<script lang=\"ts\">\n  import { ondestroy } from 'svelte';\n  import { readable } from 'svelte/store';\n\n  const current = readable(tour.current.value, (set) => {\n    set(tour.current.value);\n    return tour.current.subscribe(() => set(tour.current.value));\n  });\n  ondestroy(() => tour.dispose());\n</script>\n```\n\n:::\n\n## working with other vielzeug libraries\n\n  **refine**: `ore tour` and `ore spotlight` are the intended presentation layer; see [driving a refine presentation](#driving a refine presentation).\n  **orbit**: `current.rect` matches orbit's `rect` shape, so a custom card positions with `computeposition({ getboundingclientrect: () => current.rect ?? zero_rect }, floatingel, middleware)`.\n  **vault**: any vault store becomes a `beaconstorage` with a six line bridge (see the `beaconstorage` docs in [api reference](./api.md)).\n  **ripple**: every handle exposes ripple `readable`s; `createripple().isbatchingobservable` semantics apply when you subscribe from effects.\n\n## best practices\n\n  give every tour and coachmark a stable `id` — it is the storage key; treat renames as data migrations.\n  keep tour configs in their own modules as plain data checked with `satisfies beacontourconfig`, so steps stay reviewable data, not component code.\n  prefer `data tour=\"...\"` attributes as target selectors: they survive class renames and read as intent.\n  set a finite `targettimeoutms` in production and alert on `target missing` to catch stale selectors.\n  call `reset()` before `start()` for replay controls; never delete storage keys by hand.\n  bump `version` when a tour's meaning changes, not when its copy is typo fixed.\n  dispose handles on teardown; `tap()` subscriptions with a shared `abortsignal` clean up in one call.\n",
+      "examples": "   \ntitle: 'beacon: examples'\ndescription: practical examples and recipes for @vielzeug/beacon.\n   \n\n## examples\n\n  [getting started](./examples/getting started.md)\n"
+    },
+    "examples": [
+      {
+        "id": "coachmark",
+        "text": "coachmark   show once, dismiss, reset import { createcoachmark } from '@vielzeug/beacon'\n\nconst button = document.createelement('button')\nbutton.textcontent = 'share'\nbutton.dataset.tour = 'share'\ndocument.body.appendchild(button)\n\nconst hint = createcoachmark({\n  autoshow: false,\n  description: 'send a link that opens straight into this view.',\n  id: 'share hint',\n  target: '[data tour=\"share\"]',\n  title: 'share this board',\n})\n\nhint.tap((event) => console.log('event:', event.type))\n\n// current is the single step snapshot: step is the hint while visible, null while hidden.\nhint.current.subscribe(() => console.log('visible:', hint.current.value.step !== null))\n\nhint.show()\nconsole.log('rect anchored to button:', json.stringify(hint.current.value.rect))\n\n// hide() can come back; dismiss() records it as seen.\nhint.hide()\nhint.show()\nhint.dismiss()\n\n// once dismissed, show() is a no op until reset() or a version bump.\nhint.show()\nconsole.log('eligible after dismiss:', hint.eligible.value)\n\nhint.reset()\nconsole.log('eligible after reset:', hint.eligible.value)"
+      },
+      {
+        "id": "persist-progress",
+        "text": "persist progress   resume, finish, replay import { createtour } from '@vielzeug/beacon'\n\n// any key value object is a beaconstorage; keys arrive namespaced.\nconst db = new map()\nconst storage = {\n  get: (key) => (db.has(key) ? json.parse(db.get(key)) : null),\n  remove: (key) => db.delete(key),\n  set: (key, value) => db.set(key, json.stringify(value)),\n}\n\nconst steps = [\n  { id: 'a', title: 'first' },\n  { id: 'b', title: 'second' },\n  { id: 'c', title: 'third' },\n]\n\nconst first = createtour({ id: 'resume demo', steps, storage, targettimeoutms: 0 })\nfirst.start()\nfirst.next()\nconsole.log('first session stopped at step index:', first.current.value.stepindex)\nfirst.pause() // keeps progress so the next handle resumes\n\n// a brand new handle (next page load) resumes from the stored record.\nconst second = createtour({ id: 'resume demo', steps, storage, targettimeoutms: 0 })\nconsole.log('resumed status:', second.status.value)\nsecond.start()\nconsole.log('resumed at step:', second.current.value.step.title)\n\nsecond.finish()\nconsole.log('after finish:', second.status.value)\n\n// start() is a no op for completed tours:\nsecond.start()\nconsole.log('still:', second.status.value)\n\n// reset() makes it eligible again (what a \"replay tour\" button calls):\nsecond.reset()\nsecond.start()\nconsole.log('after reset + start, step:', second.current.value.step.title)"
+      },
+      {
+        "id": "tour-basics",
+        "text": "tour basics   steps, rects, completion import { createtour } from '@vielzeug/beacon'\n\n// a tiny stage so the tour has something real to anchor to.\nconst stage = document.createelement('div')\nstage.innerhtml = '<button data tour=\"nav\" style=\"margin:24px\">navigation</button><button data tour=\"share\" style=\"margin:24px\">share</button>'\ndocument.body.appendchild(stage)\n\nconst tour = createtour({\n  autoscroll: false, // jsdom has no real scrolling\n  id: 'repl tour',\n  steps: [\n    { id: 'welcome', title: 'welcome' },\n    { id: 'nav', target: '[data tour=\"nav\"]', title: 'navigation' },\n    { id: 'share', target: '[data tour=\"share\"]', title: 'share' },\n  ],\n  targettimeoutms: 0,\n})\n\n// readable<t>: the listener takes no arguments, read .value inside.\ntour.current.subscribe(() => {\n  const current = tour.current.value\n  if (!current.step) return\n  console.log('step ' + (current.stepindex + 1) + ' of ' + current.totalsteps + ': ' + current.step.title)\n  console.log('  anchor rect:', current.rect === null ? 'null (centered)' : json.stringify(current.rect))\n})\n\ntour.tap((event) => {\n  if (event.type === 'tour:complete') console.log('tour complete, reason:', event.reason)\n})\n\ntour.start()\ntour.next()\ntour.next()\ntour.next() // past the last step finishes the tour\n\nconsole.log('status:', tour.status.value)"
+      }
+    ],
+    "exports": "createtour createcoachmark resolvetarget",
+    "keywords": "onboarding product tour coachmark walkthrough step by step spotlight headless",
+    "name": "@vielzeug/beacon",
+    "related": "refine orbit ripple vault",
+    "slug": "beacon",
+    "source": "// public root surface of @vielzeug/beacon. every public export goes through this file.\nexport { createcoachmark } from './coachmark';\nexport { beaconconfigerror, beacondisposederror, beaconerror } from './errors';\nexport { resolvetarget } from './target';\nexport { createtour } from './tour';\nexport type {\n  beaconbaseevent,\n  beaconcoachmarkconfig,\n  beaconcoachmarkevent,\n  beaconcoachmarkhandle,\n  beaconcurrentstep,\n  beaconplacement,\n  beaconpresentation,\n  beaconprogress,\n  beaconrect,\n  beaconstatus,\n  beaconstep,\n  beaconstorage,\n  beacontarget,\n  beacontargetresolver,\n  beacontourconfig,\n  beacontourevent,\n  beacontourhandle,\n} from './types';\n"
+  },
   {
     "category": "state",
     "description": "framework neutral typed state machines with pure transitions, actor owned runtime work, timers, invokes, and explicit effects.",
@@ -1026,12 +1056,12 @@
     "category": "ui components",
     "description": "accessible, themeable web components built with ore for framework and vanilla dom apps.",
     "docs": {
-      "index": "   \ntitle: 'refine: web component library'\ndescription: accessible, themeable web components built with ore for framework and vanilla dom apps.\npackage: refine\ncategory: ui components\nkeywords: [web components, accessible, themeable, ui, components, design system]\nrelated: [ore, orbit, forge, keymap]\nexports:\n  [\n    ore accordion,\n    ore accordion item,\n    ore alert,\n    ore async,\n    ore avatar,\n    ore avatar group,\n    ore badge,\n    ore box,\n    ore breadcrumb,\n    ore breadcrumb item,\n    ore button,\n    ore button group,\n    ore calendar,\n    ore card,\n    ore carousel,\n    ore carousel slide,\n    ore chat message,\n    ore checkbox,\n    ore checkbox group,\n    ore chip,\n    ore code window,\n    ore column,\n    ore combobox,\n    ore combobox option,\n    ore command palette,\n    ore command palette item,\n    ore cookie banner,\n    ore copy command,\n    ore counter,\n    ore datagrid,\n    ore date picker,\n    ore dialog,\n    ore drawer,\n    ore file input,\n    ore grid,\n    ore grid item,\n    ore icon,\n    ore input,\n    ore keyboard key,\n    ore keyboard shortcut,\n    ore list,\n    ore list item,\n    ore marquee,\n    ore menu,\n    ore menu item,\n    ore menu separator,\n    ore message composer,\n    ore navbar,\n    ore navbar item,\n    ore navigation menu,\n    ore navigation menu item,\n    ore navigation menu panel,\n    ore number input,\n    ore otp input,\n    ore pagination,\n    ore password strength,\n    ore popover,\n    ore progress,\n    ore qr code,\n    ore qr scanner,\n    ore query bar,\n    ore radio,\n    ore radio group,\n    ore rating,\n    ore select,\n    ore separator,\n    ore sidebar,\n    ore sidebar group,\n    ore sidebar item,\n    ore skeleton,\n    ore slider,\n    ore speech player,\n    ore speed reading,\n    ore stats,\n    ore step,\n    ore stepper,\n    ore switch,\n    ore tab item,\n    ore tab panel,\n    ore table,\n    ore tabs,\n    ore td,\n    ore text,\n    ore th,\n    ore tr,\n    ore textarea,\n    ore time picker,\n    ore toast,\n    ore tooltip,\n    ore typing indicator,\n  ]\nenvironments: [browser]\n   \n\n<!   markdownlint disable md025 md033 md060   >\n\n<packagehero package=\"refine\" />\n\n## why refine?\n\nevery project needs ui primitives. refine provides accessible web components that work natively anywhere html is rendered, no framework required.\n\n```html\n<!   before: roll your own button with aria   >\n<button class=\"btn btn primary\" role=\"button\" aria pressed=\"false\" tabindex=\"0\">\n  <span class=\"btn spinner\" aria hidden=\"true\"></span>\n  save\n</button>\n\n<!   after: refine   >\n<ore button variant=\"solid\" color=\"primary\" loading>save</ore button>\n```\n\n| feature            | refine                                       | shoelace                                   | material web                               |\n|                    |                                             |                                            |                                            |\n| bundle size        | <packageinfo package=\"refine\" type=\"size\" /> | ~145 kb                                    | ~200 kb                                    |\n| built with         | ore                                       | lit                                        | lit                                        |\n| runtime dependencies | vielzeug ui primitives; lucide only for the opt in full library registrar | lit + utilities | lit + material foundations |\n| accessible         | wcag aa                                     | wcag aa                                    | wcag aa                                    |\n| framework agnostic | <ore icon name=\"check\" size=\"16\"></ore icon>  | <ore icon name=\"check\" size=\"16\"></ore icon> | <ore icon name=\"check\" size=\"16\"></ore icon> |\n\n<div class=\"decision callout\">\n\n**use refine when** you want accessible web components that match the vielzeug design system without a heavy framework dependency.\n\n**consider shoelace or material web** if your team is already standardized on those ecosystems and you need their established component catalogs.\n\n</div>\n\n## installation\n\n::: code group\n\n```sh [pnpm]\npnpm add @vielzeug/refine\n```\n\n```sh [npm]\nnpm install @vielzeug/refine\n```\n\n```sh [yarn]\nyarn add @vielzeug/refine\n```\n\n:::\n\n## quick start\n\n```ts\n// 1. import global styles once\nimport '@vielzeug/refine/fouc.css';   // hide unupgraded custom elements until first paint\nimport '@vielzeug/refine/tokens.css'; // tokens, animations, cascade layers\n\n// 2. register only the elements you need\nimport '@vielzeug/refine/button';\nimport '@vielzeug/refine/input';\nimport '@vielzeug/refine/card';\n```\n\n```html\n<ore button variant=\"solid\" color=\"primary\">save</ore button>\n<ore input label=\"email\" type=\"email\" required></ore input>\n<ore card padding=\"lg\">\n  <span slot=\"header\">account</span>\n  <p>card content goes here.</p>\n</ore card>\n```\n\n```ts\n```\n\n### cdn / vanilla html\n\nuse the self contained iife bundle to load refine directly from a cdn in any html page: no build step required:\n\n```html\n<!   1. styles   >\n<link rel=\"stylesheet\" href=\"https://unpkg.com/@vielzeug/refine/dist/styles/fouc.css\" />\n<link rel=\"stylesheet\" href=\"https://unpkg.com/@vielzeug/refine/dist/styles/tokens.css\" />\n\n<!   2. all components (iife: registers global refine namespace)   >\n<script src=\"https://unpkg.com/@vielzeug/refine/dist/refine.iife.js\"></script>\n```\n\nfor bundler based projects that still want a cdn url, use the esm bundle via an import map:\n\n```html\n<script type=\"importmap\">\n  {\n    \"imports\": {\n      \"@vielzeug/refine\": \"https://esm.sh/@vielzeug/refine\",\n      \"@vielzeug/refine/button\": \"https://esm.sh/@vielzeug/refine/button\",\n      \"@vielzeug/refine/input\": \"https://esm.sh/@vielzeug/refine/input\"\n    }\n  }\n</script>\n\n<script type=\"module\">\n  import '@vielzeug/refine/button';\n  import '@vielzeug/refine/input';\n</script>\n```\n\n### package entry points\n\n| import                   | purpose                                   |\n|                          |                                           |\n| `@vielzeug/refine/fouc.css` | fouc suppression for unupgraded custom elements |\n| `@vielzeug/refine/tokens.css` | global design tokens and cascade layers |\n| `@vielzeug/refine/styles/preflight.css` | optional browser default reset (includes fouc suppression) |\n\ncomponent registration happens through side effect imports such as `@vielzeug/refine/button` and `@vielzeug/refine/dialog`.\n\n### components\n\n**content:** `ore avatar`, `ore avatar group`, `ore breadcrumb`, `ore card`, `ore carousel`, `ore carousel slide`, `ore chat message`, `ore icon`, `ore keyboard key`, `ore keyboard shortcut`, `ore list`, `ore list item`, `ore marquee`, `ore pagination`, `ore qr code`, `ore separator`, `ore speed reading`, `ore stats`, `ore step`, `ore stepper`, `ore table`, `ore text`\n\n**disclosure:** `ore accordion`, `ore accordion item`, `ore tabs`, `ore tab item`, `ore tab panel`\n\n**feedback:** `ore alert`, `ore async`, `ore badge`, `ore chip`, `ore cookie banner`, `ore password strength`, `ore progress`, `ore skeleton`, `ore toast`, `ore typing indicator`\n\n**inputs:** `ore button`, `ore button group`, `ore calendar`, `ore checkbox`, `ore checkbox group`, `ore column`, `ore combobox`, `ore counter`, `ore datagrid`, `ore date picker`, `ore file input`, `ore input`, `ore message composer`, `ore number input`, `ore otp input`, `ore qr scanner`, `ore query bar`, `ore radio`, `ore radio group`, `ore rating`, `ore select`, `ore slider`, `ore switch`, `ore textarea`, `ore time picker`\n\n**layout:** `ore box`, `ore grid`, `ore grid item`, `ore navbar`, `ore sidebar`\n\n**overlay:** `ore command palette`, `ore command palette item`, `ore dialog`, `ore drawer`, `ore menu`, `ore popover`, `ore tooltip`\n\n## component portfolio\n\nrefine keeps one public package and classifies components by composition level rather than stability. all listed components remain supported and tested.\n\n  **foundations**: buttons, inputs, selection controls, disclosure, dialogs, menus, tooltips, layout primitives, and feedback indicators. start here when building an application specific interface.\n  **composed patterns**: data grids, command palettes, navigation menus, steppers, calendars, date/time pickers, file inputs, and message composers. these package recurring accessibility and interaction behavior that is costly to rebuild correctly.\n  **presentation patterns**: cards, chat messages, code windows, stats, marquees, avatars, badges, and skeletons. use these when their product vocabulary matches the application; prefer foundations when it does not.\n\nclassification guides discovery and bundle selection. it is not a reason to remove working components or move them into unstable packages; per component subpath imports remain the tree shaking boundary.\n\n## features\n\n<div class=\"features grid\">\n\n  **accessible**: keyboard navigation, aria wiring, and focus management across interactive components\n  **themeable**: global tokens plus component level css custom properties\n  **framework agnostic**: works anywhere html can be rendered\n  **tree shakeable**: import only the component entry points you register\n  **comprehensive surface**: inputs, content, disclosure, feedback, layout, and overlay primitives\n  **native form integration**: form associated controls submit values, validate supported required constraints, and reset with their form\n  **typed framework declarations**: dom, react, and vue tags derive from the component property contracts\n\n</div>\n\n### prerequisites\n\n  browser runtime with custom elements support.\n  import `@vielzeug/refine/fouc.css` and `@vielzeug/refine/tokens.css` before rendering components.\n  for ssr, render placeholders server side and hydrate components only on the client.\n\n## documentation\n\n<div class=\"doc links\">\n\n  [usage guide](./usage.md)\n  [api reference](./api.md)\n  [migration guide](./migration.md)\n\n</div>\n\n## see also\n\n<div class=\"see also\">\n\n  [ore](/ore/): web component runtime that powers refine\n  [orbit](/orbit/): floating ui positioning used in refine's overlays\n  [forge](/forge/): form state management for use with refine inputs\n  [keymap](/keymap/): keyboard shortcut manager that powers the command palette's global trigger\n\n</div>\n\n<!   markdownlint enable md025 md033 md060   >\n",
+      "index": "   \ntitle: 'refine: web component library'\ndescription: accessible, themeable web components built with ore for framework and vanilla dom apps.\npackage: refine\ncategory: ui components\nkeywords: [web components, accessible, themeable, ui, components, design system]\nrelated: [ore, orbit, forge, keymap]\nexports:\n  [\n    ore accordion,\n    ore accordion item,\n    ore alert,\n    ore async,\n    ore avatar,\n    ore avatar group,\n    ore badge,\n    ore box,\n    ore breadcrumb,\n    ore breadcrumb item,\n    ore button,\n    ore button group,\n    ore calendar,\n    ore card,\n    ore carousel,\n    ore carousel slide,\n    ore chat message,\n    ore checkbox,\n    ore checkbox group,\n    ore chip,\n    ore code window,\n    ore column,\n    ore combobox,\n    ore combobox option,\n    ore command palette,\n    ore command palette item,\n    ore cookie banner,\n    ore copy command,\n    ore counter,\n    ore datagrid,\n    ore date picker,\n    ore dialog,\n    ore drawer,\n    ore file input,\n    ore grid,\n    ore grid item,\n    ore icon,\n    ore input,\n    ore keyboard key,\n    ore keyboard shortcut,\n    ore list,\n    ore list item,\n    ore marquee,\n    ore menu,\n    ore menu item,\n    ore menu separator,\n    ore message composer,\n    ore navbar,\n    ore navbar item,\n    ore navigation menu,\n    ore navigation menu item,\n    ore navigation menu panel,\n    ore number input,\n    ore otp input,\n    ore pagination,\n    ore password strength,\n    ore popover,\n    ore progress,\n    ore qr code,\n    ore qr scanner,\n    ore query bar,\n    ore radio,\n    ore radio group,\n    ore rating,\n    ore select,\n    ore separator,\n    ore sidebar,\n    ore sidebar group,\n    ore sidebar item,\n    ore skeleton,\n    ore slider,\n    ore speech player,\n    ore speed reading,\n    ore spotlight,\n    ore stats,\n    ore step,\n    ore stepper,\n    ore switch,\n    ore tab item,\n    ore tab panel,\n    ore table,\n    ore tabs,\n    ore td,\n    ore text,\n    ore th,\n    ore tr,\n    ore textarea,\n    ore time picker,\n    ore toast,\n    ore tooltip,\n    ore tour,\n    ore typing indicator,\n  ]\nenvironments: [browser]\n   \n\n<!   markdownlint disable md025 md033 md060   >\n\n<packagehero package=\"refine\" />\n\n## why refine?\n\nevery project needs ui primitives. refine provides accessible web components that work natively anywhere html is rendered, no framework required.\n\n```html\n<!   before: roll your own button with aria   >\n<button class=\"btn btn primary\" role=\"button\" aria pressed=\"false\" tabindex=\"0\">\n  <span class=\"btn spinner\" aria hidden=\"true\"></span>\n  save\n</button>\n\n<!   after: refine   >\n<ore button variant=\"solid\" color=\"primary\" loading>save</ore button>\n```\n\n| feature            | refine                                       | shoelace                                   | material web                               |\n|                    |                                             |                                            |                                            |\n| bundle size        | <packageinfo package=\"refine\" type=\"size\" /> | ~145 kb                                    | ~200 kb                                    |\n| built with         | ore                                       | lit                                        | lit                                        |\n| runtime dependencies | vielzeug ui primitives; lucide only for the opt in full library registrar | lit + utilities | lit + material foundations |\n| accessible         | wcag aa                                     | wcag aa                                    | wcag aa                                    |\n| framework agnostic | <ore icon name=\"check\" size=\"16\"></ore icon>  | <ore icon name=\"check\" size=\"16\"></ore icon> | <ore icon name=\"check\" size=\"16\"></ore icon> |\n\n<div class=\"decision callout\">\n\n**use refine when** you want accessible web components that match the vielzeug design system without a heavy framework dependency.\n\n**consider shoelace or material web** if your team is already standardized on those ecosystems and you need their established component catalogs.\n\n</div>\n\n## installation\n\n::: code group\n\n```sh [pnpm]\npnpm add @vielzeug/refine\n```\n\n```sh [npm]\nnpm install @vielzeug/refine\n```\n\n```sh [yarn]\nyarn add @vielzeug/refine\n```\n\n:::\n\n## quick start\n\n```ts\n// 1. import global styles once\nimport '@vielzeug/refine/fouc.css';   // hide unupgraded custom elements until first paint\nimport '@vielzeug/refine/tokens.css'; // tokens, animations, cascade layers\n\n// 2. register only the elements you need\nimport '@vielzeug/refine/button';\nimport '@vielzeug/refine/input';\nimport '@vielzeug/refine/card';\n```\n\n```html\n<ore button variant=\"solid\" color=\"primary\">save</ore button>\n<ore input label=\"email\" type=\"email\" required></ore input>\n<ore card padding=\"lg\">\n  <span slot=\"header\">account</span>\n  <p>card content goes here.</p>\n</ore card>\n```\n\n```ts\n```\n\n### cdn / vanilla html\n\nuse the self contained iife bundle to load refine directly from a cdn in any html page: no build step required:\n\n```html\n<!   1. styles   >\n<link rel=\"stylesheet\" href=\"https://unpkg.com/@vielzeug/refine/dist/styles/fouc.css\" />\n<link rel=\"stylesheet\" href=\"https://unpkg.com/@vielzeug/refine/dist/styles/tokens.css\" />\n\n<!   2. all components (iife: registers global refine namespace)   >\n<script src=\"https://unpkg.com/@vielzeug/refine/dist/refine.iife.js\"></script>\n```\n\nfor bundler based projects that still want a cdn url, use the esm bundle via an import map:\n\n```html\n<script type=\"importmap\">\n  {\n    \"imports\": {\n      \"@vielzeug/refine\": \"https://esm.sh/@vielzeug/refine\",\n      \"@vielzeug/refine/button\": \"https://esm.sh/@vielzeug/refine/button\",\n      \"@vielzeug/refine/input\": \"https://esm.sh/@vielzeug/refine/input\"\n    }\n  }\n</script>\n\n<script type=\"module\">\n  import '@vielzeug/refine/button';\n  import '@vielzeug/refine/input';\n</script>\n```\n\n### package entry points\n\n| import                   | purpose                                   |\n|                          |                                           |\n| `@vielzeug/refine/fouc.css` | fouc suppression for unupgraded custom elements |\n| `@vielzeug/refine/tokens.css` | global design tokens and cascade layers |\n| `@vielzeug/refine/styles/preflight.css` | optional browser default reset (includes fouc suppression) |\n\ncomponent registration happens through side effect imports such as `@vielzeug/refine/button` and `@vielzeug/refine/dialog`.\n\n### components\n\n**content:** `ore avatar`, `ore avatar group`, `ore breadcrumb`, `ore card`, `ore carousel`, `ore carousel slide`, `ore chat message`, `ore icon`, `ore keyboard key`, `ore keyboard shortcut`, `ore list`, `ore list item`, `ore marquee`, `ore pagination`, `ore qr code`, `ore separator`, `ore speed reading`, `ore stats`, `ore step`, `ore stepper`, `ore table`, `ore text`\n\n**disclosure:** `ore accordion`, `ore accordion item`, `ore tabs`, `ore tab item`, `ore tab panel`\n\n**feedback:** `ore alert`, `ore async`, `ore badge`, `ore chip`, `ore cookie banner`, `ore password strength`, `ore progress`, `ore skeleton`, `ore toast`, `ore typing indicator`\n\n**inputs:** `ore button`, `ore button group`, `ore calendar`, `ore checkbox`, `ore checkbox group`, `ore column`, `ore combobox`, `ore counter`, `ore datagrid`, `ore date picker`, `ore file input`, `ore input`, `ore message composer`, `ore number input`, `ore otp input`, `ore qr scanner`, `ore query bar`, `ore radio`, `ore radio group`, `ore rating`, `ore select`, `ore slider`, `ore switch`, `ore textarea`, `ore time picker`\n\n**layout:** `ore box`, `ore grid`, `ore grid item`, `ore navbar`, `ore sidebar`\n\n**overlay:** `ore command palette`, `ore command palette item`, `ore dialog`, `ore drawer`, `ore menu`, `ore popover`, `ore spotlight`, `ore tooltip`, `ore tour`\n\n## component portfolio\n\nrefine keeps one public package and classifies components by composition level rather than stability. all listed components remain supported and tested.\n\n  **foundations**: buttons, inputs, selection controls, disclosure, dialogs, menus, tooltips, layout primitives, and feedback indicators. start here when building an application specific interface.\n  **composed patterns**: data grids, command palettes, navigation menus, steppers, calendars, date/time pickers, file inputs, and message composers. these package recurring accessibility and interaction behavior that is costly to rebuild correctly.\n  **presentation patterns**: cards, chat messages, code windows, stats, marquees, avatars, badges, and skeletons. use these when their product vocabulary matches the application; prefer foundations when it does not.\n\nclassification guides discovery and bundle selection. it is not a reason to remove working components or move them into unstable packages; per component subpath imports remain the tree shaking boundary.\n\n## features\n\n<div class=\"features grid\">\n\n  **accessible**: keyboard navigation, aria wiring, and focus management across interactive components\n  **themeable**: global tokens plus component level css custom properties\n  **framework agnostic**: works anywhere html can be rendered\n  **tree shakeable**: import only the component entry points you register\n  **comprehensive surface**: inputs, content, disclosure, feedback, layout, and overlay primitives\n  **native form integration**: form associated controls submit values, validate supported required constraints, and reset with their form\n  **typed framework declarations**: dom, react, and vue tags derive from the component property contracts\n\n</div>\n\n### prerequisites\n\n  browser runtime with custom elements support.\n  import `@vielzeug/refine/fouc.css` and `@vielzeug/refine/tokens.css` before rendering components.\n  for ssr, render placeholders server side and hydrate components only on the client.\n\n## documentation\n\n<div class=\"doc links\">\n\n  [usage guide](./usage.md)\n  [api reference](./api.md)\n  [migration guide](./migration.md)\n\n</div>\n\n## see also\n\n<div class=\"see also\">\n\n  [ore](/ore/): web component runtime that powers refine\n  [orbit](/orbit/): floating ui positioning used in refine's overlays\n  [forge](/forge/): form state management for use with refine inputs\n  [keymap](/keymap/): keyboard shortcut manager that powers the command palette's global trigger\n\n</div>\n\n<!   markdownlint enable md025 md033 md060   >\n",
       "api": "   \ntitle: 'refine: api reference'\ndescription: published component, stylesheet, framework type, and error entry points for @vielzeug/refine.\n   \n\n[[toc]]\n\n## api overview\n\n| symbol | purpose | execution mode | common gotcha |\n|     |     |     |     |\n| `@vielzeug/refine/<component>` | register one custom element and export its public types | sync | importing a type alone does not register the element |\n| `@vielzeug/refine/tokens.css` | load required theme tokens, animations, and cascade layers | css | import once before components render |\n| `@vielzeug/refine/fouc.css` | hide unregistered `ore *` elements until upgrade | css | load before first paint |\n| `@vielzeug/refine/styles/preflight.css` | apply the optional browser reset | css | the reset affects global elements |\n| `@vielzeug/refine/frameworks/elements` | register typed dom tag mappings | types only | import for side effects in typescript |\n| `@vielzeug/refine/frameworks/react` | register typed react jsx elements | types only | does not provide runtime wrappers |\n| `@vielzeug/refine/frameworks/vue` | register typed vue global components | types only | does not install a vue plugin |\n| `@vielzeug/refine/theme` | `createthemecontroller()`: light/dark/system document theme | sync | does not persist the preference or set an accent color |\n| `eventfieldvalue()` / `eventfieldchecked()` | read a form control's value/checked from `event.currenttarget` | sync | exported from the package root; guards non field targets |\n| `refineerror` | base class for package defined public errors | sync | component configuration warnings do not throw this error |\n\n## package entry point\n\n| import | purpose |\n|     |     |\n| `@vielzeug/refine` | export `registericons`, icon definition types, `refineerror`, and the field readers without registering components |\n| `@vielzeug/refine/<component>` | register one component and export its tag constant, props, events, and related types |\n| `@vielzeug/refine/theme` | `createthemecontroller()` and its theme types |\n| `@vielzeug/refine/tokens.css` | required global design contract |\n| `@vielzeug/refine/fouc.css` | optional pre upgrade visibility rule |\n| `@vielzeug/refine/styles/*` | focused theme, animation, layer, and preflight stylesheets |\n| `@vielzeug/refine/frameworks/*` | typescript augmentations for dom, react, and vue |\n\n## icon registration and adapters\n\n`registericons(icons: readonly<record<string, icondefinition>>): void` is available from `@vielzeug/refine/icons`, `@vielzeug/refine`, and `@vielzeug/refine/icon`. the common `icons` entry and root remain free of component registration side effects.\n\n`icondefinition`, `iconelement`, and `iconattributes` are exported from all three entries. shared definition and registration modules live in `src/icons/`, alongside adapters and internal svg helpers/defaults. definitions contain a numeric `viewbox` tuple, optional presentation attributes, and recursive svg children; they do not require a provider identity. invalid registrations throw the root exported `refineerror` atomically.\n\n| entry | export | purpose |\n|     |     |     |\n| `@vielzeug/refine/icons` | `registericons`, `icondefinition`, `iconelement`, `iconattributes` | common library neutral registration and definition api |\n| `@vielzeug/refine/icons/lucide` | `lucideicons`, `lucideicondata` | pure adapter for selected structural lucide svg data |\n| `@vielzeug/refine/icons/lucide/all` | side effect registration | explicitly register the full installed lucide library |\n| `@vielzeug/refine/icons/heroicons` | `heroiconsicons`, `iconifyicon` | convert a caller named map of individual heroicons iconify data |\n| `@vielzeug/refine/icons/tabler` | `tablericons`, `iconifyicon` | convert a caller named map of individual tabler iconify data |\n| `@vielzeug/refine/icons/mdi` | `mdiicons`, `iconifyicon` | convert a caller named map of individual mdi iconify data |\n| `@vielzeug/refine/icons/iconify` | `iconifyicon`, `iconifyicons` | convert individual iconify data or selected/complete collections |\n| `@vielzeug/refine/icons/iconify` | `iconifyicon`, `iconifyalias`, `iconifycollection`, `iconifytransform` | structural data types; no iconify dependency required |\n\nlucide is an optional peer, not a mandatory dependency. only `icons/lucide/all` requires an installed `lucide` package; consumers selecting that entry declare it themselves. the structural `icons/lucide` adapter accepts supplied data without importing lucide.\n\nthe standalone iife exposes `registericons`, `lucideicons`, `heroiconsicons`, `tablericons`, `mdiicons`, `iconifyicon`, and `iconifyicons` under `refine.components.content`. neither the iife nor component entries import lucide. iconify conversion drops provider `class` metadata, validates finite numeric offsets and positive finite dimensions before transforms, and retains the strict svg allowlist. see the [icon reference](./components/icon.md) for presentation overrides, local svg id rewriting, supported families, and licenses.\n\nthe three family adapters share this signature:\n\n```ts\nheroiconsicons(icons: readonly<record<string, iconifyicon>>): record<string, icondefinition>;\ntablericons(icons: readonly<record<string, iconifyicon>>): record<string, icondefinition>;\nmdiicons(icons: readonly<record<string, iconifyicon>>): record<string, icondefinition>;\n```\n\neach accepts individual iconify svg data, preserves input keys without adding a namespace, and returns definitions without registering them. they require `domparser`, preserve each icon's geometry/presentation/transforms, and throw `refineerror` for invalid iconify data. they do not accept react/vue components, collection json, or raw svg path strings. use `iconifyicons(collection, names?)` for collections and alias resolution.\n\n## styles\n\n```ts\nimport '@vielzeug/refine/fouc.css';\nimport '@vielzeug/refine/tokens.css';\nimport '@vielzeug/refine/styles/preflight.css';\n```\n\n`tokens.css` is required. it defines tokens, animations, and cascade layer order without resetting global elements. `preflight.css` is optional and includes fouc suppression.\n\n| import path | purpose |\n|     |     |\n| `@vielzeug/refine/fouc.css` | fouc suppression for unupgraded custom elements |\n| `@vielzeug/refine/tokens.css` | tokens, animation helpers, and cascade layers |\n| `@vielzeug/refine/styles/theme.css` | theme token declarations |\n| `@vielzeug/refine/styles/animation.css` | animation helpers |\n| `@vielzeug/refine/styles/layers.css` | cascade layer declarations |\n| `@vielzeug/refine/styles/preflight.css` | optional browser reset and fouc suppression |\n\n## components\n\neach component uses one registration and type entry point:\n\n```ts\nimport '@vielzeug/refine/button';\nimport type { orebuttonprops } from '@vielzeug/refine/button';\n```\n\n| area | components |\n|     |     |\n| content | `avatar`, `avatar group`, `breadcrumb`, `card`, `carousel`, `chat message`, `code window`, `copy command`, `icon`, `keyboard key`, `list`, `list item`, `marquee`, `pagination`, `separator`, `speech player`, `speed reading`, `stats`, `step`, `stepper`, `table`, `text` |\n| disclosure | `accordion`, `accordion item`, `tabs`, `tab item`, `tab panel` |\n| feedback | `alert`, `async`, `badge`, `chip`, `cookie banner`, `password strength`, `progress`, `skeleton`, `toast`, `typing indicator` |\n| inputs | `button`, `button group`, `calendar`, `checkbox`, `checkbox group`, `combobox`, `counter`, `datagrid`, `date picker`, `file input`, `input`, `message composer`, `number input`, `otp input`, `query bar`, `radio`, `radio group`, `rating`, `select`, `slider`, `switch`, `textarea`, `time picker` |\n| layout | `box`, `grid`, `grid item`, `navbar`, `sidebar` |\n| overlays | `command palette`, `dialog`, `drawer`, `menu`, `navigation menu`, `popover`, `tooltip` |\n\neach component page lists its attributes, javascript properties, events, slots, parts, and css custom properties.\n\nthe [`query bar`](./components/query bar.md) entry also exports `querystate`, `querytokendef`, `queryquickfilter`, `querybarlabels`, and pure grammar helpers. vocabulary entries default to single selection; `selection: 'multiple'` allows distinct values for the same key. `anylabel` customizes the unrestricted single selection choice, such as “default order” for sorting. options accept an optional `icon` (registered `ore icon` name), displayed beside their labels in the drawer. `tokenvalues(state, key)` reads all values, `removetoken(state, token)` removes an exact pair, and `cleartokens(state, key)` clears a group. its unified field contains applied filters, with a compact secondary row for filter entry, quick toggles, and a `toolbar end` slot for application content such as a result count. drawer selection uses the same state and vocabulary as typed suggestions. pending edits block incidental backdrop/swipe dismissal; explicit cancel, close, and escape discard them. search hidden selections remain visible in a summary.\n\n## framework types\n\n```ts\nimport type {} from '@vielzeug/refine/frameworks/elements';\nimport type {} from '@vielzeug/refine/frameworks/react';\nimport type {} from '@vielzeug/refine/frameworks/vue';\n```\n\nthe declarations cover every supported tag and derive component properties from refine's authoritative `htmlelementtagnamemap`. they provide types only; component registration still uses component subpaths.\n\n## events and form controls\n\nform controls expose `.value` or `.checked` and dispatch standard `input` and `change` events. read the property from `event.currenttarget`.\n\nfinite choice properties use ore's `prop.oneof()` parsing: values outside a component's documented options resolve to\nthe declared default, or `undefined` when no default is declared.\n\nform associated controls participate in native form submission, validity checks, and reset. a named control's value\nis available through `new formdata(form)`, and supported `required` constraints affect `form.checkvalidity()`,\n`form.reportvalidity()`, and submit blocking. the `error` property renders and announces feedback; it does not by\nitself set native constraint validity.\n\nstateful overlays expose controlled `open`, optional `default open`, and an `open change` custom event with `{ open, reason }` detail. component pages define additional detail fields and reasons.\n\n## utilities\n\n### `createthemecontroller(options?)`\n\n```ts\nimport { createthemecontroller } from '@vielzeug/refine/theme';\n\nconst theme = createthemecontroller(); // starts in 'system' mode\ntheme.setpreference('dark');\ntheme.dispose();\n```\n\nowns the light/dark/system theme for the document: a reactive `preference` signal, the effective `resolved` mode (`'dark' | 'light'` after resolving `system` against the os), and the dom application `styles/theme.css` expects: the `.dark` class plus the `color scheme` property on the root element, so every `light dark()` token resolves to the right branch. while in `system` mode the controller tracks the os `prefers color scheme` via sentinel's `createmediaquery`.\n\nthe controller does **not** persist the preference or expose an accent color: those are consumer concerns (wire `watch(controller.preference, save)` for persistence; set `  color primary hue` yourself). options: `initial` (starting preference, default `'system'`), `root` (element carrying the classes, default `document.documentelement`), `target` (window whose `matchmedia` backs `system`). the handle is disposable: `dispose()`, `disposed`, `disposalsignal`, `[symbol.dispose]`.\n\n### `eventfieldvalue(event)` / `eventfieldchecked(event)`\n\n```ts\nimport { eventfieldchecked, eventfieldvalue } from '@vielzeug/refine';\n\ninput.addeventlistener('input', (event) => {\n  const value = eventfieldvalue(event); // string | undefined: never a blind cast\n});\n```\n\nguarded readers for the standard `input`/`change` event pattern above: they read `value`/`checked` from `event.currenttarget` only when the target actually carries it, so a handler wired to the wrong element yields `undefined`/`false` instead of a crash or a lie. exported from the package root, which registers no components.\n\n## types\n\ncomponent props follow the `ore<component>props` naming pattern. event maps follow `ore<component>events`. import both from the component subpath that owns them.\n\n`refineelementmap`, `refinereactintrinsicelements`, and `refinevueglobalcomponents` are exported from their respective `frameworks/*` type entry points.\n\n## errors\n\n### `refineerror`\n\n```ts\nclass refineerror extends error {\n  constructor(message: string, opts?: erroroptions);\n}\n```\n\nbase class for public refine errors. it preserves `cause` through `erroroptions`.\n",
       "usage": "   \ntitle: 'refine: usage guide'\ndescription: register refine components, configure properties, handle events, compose slots, and integrate frameworks.\n   \n\n[[toc]]\n\n## basic usage\n\nload the global design contract once, then register only the components used by the page.\n\n```ts\nimport '@vielzeug/refine/tokens.css';\nimport '@vielzeug/refine/button';\nimport '@vielzeug/refine/input';\nimport '@vielzeug/refine/dialog';\n\nconst input = document.queryselector('ore input');\nconst save = document.queryselector('ore button');\n\nif (!(input instanceof htmlelement) || !(save instanceof htmlelement)) {\n  throw new error('expected refine controls');\n}\n\nsave.addeventlistener('click', () => {\n  console.log((input as htmlelement & { value: string }).value);\n});\n```\n\nadd the browser reset only when the application owns global element styling:\n\n```ts\nimport '@vielzeug/refine/styles/preflight.css';\n```\n\n## choose an icon library\n\nrefine includes only its internal component icons. register application icons before mounting them: use `registericons` and neutral `icondefinition` data from `@vielzeug/refine/icons`, the pure `@vielzeug/refine/icons/lucide` adapter for selected lucide icons, or `@vielzeug/refine/icons/iconify` for local heroicons, tabler, and material design icons data. keep importing the component from `@vielzeug/refine/icon`. lucide is an optional peer: install `lucide` yourself only when choosing its data or `@vielzeug/refine/icons/lucide/all`; core and structural adapters do not require it. the [icon reference](./components/icon.md) covers imports, licenses, and presentation behavior.\n\nfor selected individual iconify data, use `heroiconsicons`, `tablericons`, or `mdiicons` from `@vielzeug/refine/icons/heroicons`, `/tabler`, or `/mdi`. for example, `registericons(heroiconsicons({ search, home }))` preserves your app keys. install the matching `@iconify icons/<family>` data package yourself; these helpers do not accept framework components. keep `iconifyicons` for collection json and aliases.\n\n## set attributes and properties\n\nuse attributes for serializable html state.\n\n```html\n<ore button variant=\"outline\" color=\"secondary\" size=\"lg\" disabled>\n  save changes\n</ore button>\n```\n\nuse javascript properties for arrays, objects, callbacks, and controlled state.\n\n```ts\nimport '@vielzeug/refine/datagrid';\nimport type { oredatagridprops } from '@vielzeug/refine/datagrid';\n\nconst grid = document.queryselector('ore datagrid') as htmlelement & oredatagridprops;\ngrid.columns = [\n  { key: 'name', label: 'name', sortable: true },\n  { key: 'role', label: 'role' },\n];\ngrid.rows = [\n  { id: '1', name: 'ada', role: 'admin' },\n  { id: '2', name: 'linus', role: 'editor' },\n];\n```\n\nenumerated properties such as `variant`, `size`, and `color` accept the values listed on each component's reference\npage. an unsupported value resolves to the property's declared default (or `undefined` when it has no default).\n\nin an ore template, `model()` can bind a refine field's `value` to a ripple signal and write user input back:\n\n```ts\nimport { signal } from '@vielzeug/ripple';\nimport { html, model } from '@vielzeug/ore';\nimport '@vielzeug/refine/input';\n\nconst email = signal('');\nconst field = html`<ore input label=\"email\" type=\"email\" value=${model(email)} />`;\n```\n\n## handle events\n\nform controls dispatch standard `input` and `change` events. read their current property from `event.currenttarget`.\n\n```ts\nconst input = document.queryselector('ore input');\ninput?.addeventlistener('input', (event) => {\n  const target = event.currenttarget as htmlelement & { value: string };\n  console.log(target.value);\n});\n```\n\ncustom events use kebab case names and typed detail objects.\n\n```ts\nimport type { oredialogevents } from '@vielzeug/refine/dialog';\n\nconst dialog = document.queryselector('ore dialog');\ndialog?.addeventlistener('open change', (event: customevent<oredialogevents['open change']>) => {\n  console.log(event.detail.open, event.detail.reason);\n});\n```\n\n## native form validation\n\nrefine's form associated controls integrate with native form submission, `formdata`, validity checks, and reset.\nuse `required` for a required value constraint; setting `error` displays and announces feedback but does not, by\nitself, invalidate the form.\n\n```html\n<form id=\"profile form\">\n  <ore input name=\"email\" type=\"email\" label=\"email\" required></ore input>\n  <ore select name=\"role\" label=\"role\" required>\n    <option value=\"\">choose a role…</option>\n    <option value=\"editor\">editor</option>\n    <option value=\"admin\">admin</option>\n  </ore select>\n  <ore button type=\"submit\">save</ore button>\n</form>\n\n<script type=\"module\">\n  import '@vielzeug/refine/input';\n  import '@vielzeug/refine/select';\n  import '@vielzeug/refine/button';\n\n  const form = document.queryselector('#profile form');\n  form.addeventlistener('submit', (event) => {\n    event.preventdefault();\n    console.log(new formdata(form).get('email'));\n  });\n</script>\n```\n\nthe browser runs native validation before dispatching `submit`. call `form.reportvalidity()` to show validation\nfeedback directly, or `form.checkvalidity()` for a boolean check without the browser's validation ui.\n\n## compose slots\n\ndefault slots hold primary content. named slots identify component owned regions.\n\n```html\n<ore card>\n  <span slot=\"header\">account</span>\n  <p>profile settings</p>\n  <div slot=\"footer\">\n    <ore button variant=\"ghost\">cancel</ore button>\n    <ore button>save</ore button>\n  </div>\n</ore card>\n```\n\ninput components commonly expose `prefix`, `suffix`, `label`, `helper`, and `error` slots. each component reference lists its supported slots.\n\n## load typescript framework declarations\n\nimport the declaration matching the framework once in an application type entry point.\n\n::: code group\n\n```ts [dom]\nimport type {} from '@vielzeug/refine/frameworks/elements';\n```\n\n```ts [react]\nimport type {} from '@vielzeug/refine/frameworks/react';\n```\n\n```ts [vue]\nimport type {} from '@vielzeug/refine/frameworks/vue';\n```\n\n:::\n\nthese entry points provide typed tags and component properties. they do not register components or install runtime adapters.\n\n## framework integration\n\nrefine elements use native dom properties, events, and slots. frameworks differ only in how they forward custom element properties and events.\n\n::: code group\n\n```tsx [react 19]\nimport '@vielzeug/refine/button';\n\nexport function savebutton() {\n  return <ore button variant=\"solid\">save</ore button>;\n}\n```\n\n```vue [vue 3]\n<script setup lang=\"ts\">\nimport '@vielzeug/refine/button';\n</script>\n\n<template>\n  <ore button variant=\"solid\">save</ore button>\n</template>\n```\n\n```svelte [svelte]\n<script lang=\"ts\">\n  import '@vielzeug/refine/button';\n</script>\n\n<ore button variant=\"solid\">save</ore button>\n```\n\n:::\n\nsee [framework integration](./frameworks.md) for custom events, controlled properties, ssr guards, and framework specific configuration.\n\n## working with other vielzeug libraries\n\n### ore\n\nuse ore when authoring a custom element that composes refine components.\n\n```ts\nimport '@vielzeug/refine/button';\nimport { define, html } from '@vielzeug/ore';\n\ndefine('save panel', {\n  setup() {\n    return html`<ore button @click=${() => console.log('save')}>save</ore button>`;\n  },\n});\n```\n\n### ripple\n\nuse ripple to drive component properties from application state.\n\n```ts\nimport '@vielzeug/refine/button';\nimport { effect, signal } from '@vielzeug/ripple';\n\nconst loading = signal(false);\nconst button = document.queryselector('ore button') as htmlelement & { loading?: boolean };\nconst loadingeffect = effect(() => {\n  button.loading = loading.value;\n});\n\nloadingeffect.dispose();\n```\n\n## best practices\n\n  **import** `tokens.css` once before rendering components.\n  **register** components through explicit subpaths.\n  **set** structured data and callbacks as javascript properties.\n  **read** form state from the event target instead of custom event payloads.\n  **provide** accessible labels for icon only controls.\n  **use** component reference pages for supported slots, parts, and css properties.\n  **dispose** application owned ripple effects and service handles.\n  **guard** dom dependent component registration during ssr.\n  **working with ai agents?** install the `vielzeug` skill (`npx  y @vielzeug/codex skills install`) so agents reach for refine components and tokens instead of custom widgets: see the [codex usage guide](../codex/usage.md#agent skill).\n"
     },
     "examples": [],
-    "exports": "ore accordion ore accordion item ore alert ore async ore avatar ore avatar group ore badge ore box ore breadcrumb ore breadcrumb item ore button ore button group ore calendar ore card ore carousel ore carousel slide ore chat message ore checkbox ore checkbox group ore chip ore code window ore column ore combobox ore combobox option ore command palette ore command palette item ore cookie banner ore copy command ore counter ore datagrid ore date picker ore dialog ore drawer ore file input ore grid ore grid item ore icon ore input ore keyboard key ore keyboard shortcut ore list ore list item ore marquee ore menu ore menu item ore menu separator ore message composer ore navbar ore navbar item ore navigation menu ore navigation menu item ore navigation menu panel ore number input ore otp input ore pagination ore password strength ore popover ore progress ore qr code ore qr scanner ore query bar ore radio ore radio group ore rating ore select ore separator ore sidebar ore sidebar group ore sidebar item ore skeleton ore slider ore speech player ore speed reading ore stats ore step ore stepper ore switch ore tab item ore tab panel ore table ore tabs ore td ore text ore th ore tr ore textarea ore time picker ore toast ore tooltip ore typing indicator",
+    "exports": "ore accordion ore accordion item ore alert ore async ore avatar ore avatar group ore badge ore box ore breadcrumb ore breadcrumb item ore button ore button group ore calendar ore card ore carousel ore carousel slide ore chat message ore checkbox ore checkbox group ore chip ore code window ore column ore combobox ore combobox option ore command palette ore command palette item ore cookie banner ore copy command ore counter ore datagrid ore date picker ore dialog ore drawer ore file input ore grid ore grid item ore icon ore input ore keyboard key ore keyboard shortcut ore list ore list item ore marquee ore menu ore menu item ore menu separator ore message composer ore navbar ore navbar item ore navigation menu ore navigation menu item ore navigation menu panel ore number input ore otp input ore pagination ore password strength ore popover ore progress ore qr code ore qr scanner ore query bar ore radio ore radio group ore rating ore select ore separator ore sidebar ore sidebar group ore sidebar item ore skeleton ore slider ore speech player ore speed reading ore spotlight ore stats ore step ore stepper ore switch ore tab item ore tab panel ore table ore tabs ore td ore text ore th ore tr ore textarea ore time picker ore toast ore tooltip ore tour ore typing indicator",
     "keywords": "web components accessible themeable ui components design system",
     "name": "@vielzeug/refine",
     "related": "ore orbit forge keymap",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vielzeug/codex",
-  "version": "26.10.15",
+  "version": "26.10.16",
   "description": "MCP server exposing all Vielzeug docs to AI clients",
   "repository": {
     "type": "git",
@@ -58,12 +58,12 @@
     "verify:exports": "node verify-exports.mjs"
   },
   "dependencies": {
-    "@modelcontextprotocol/server": "2.1.0"
+    "@modelcontextprotocol/server": "2.3.1"
   },
   "devDependencies": {
-    "@types/node": "^26.6.2",
-    "@vielzeug/refine": "26.10.15",
+    "@types/node": "^26.6.5",
+    "@vielzeug/refine": "26.10.16",
     "typescript": "^6.0.3",
-    "vitest": "^5.0.1"
+    "vitest": "^5.0.5"
   }
 }

package/skills/vielzeug/SKILL.md

@@ -40,6 +40,7 @@ If a need matches a package below, use that package. Do not reimplement signals,
 - `@vielzeug/archive`: Community content publishing for Cloudflare Workers + D1: a hardened Worker core over per-collection payload schemas
 - `@vielzeug/arsenal`: Non-trivial TypeScript utilities: retry, cancellation, cache, safe-path, serialization, prototype-pollution-guarded collections
 - `@vielzeug/assay`: Framework-agnostic DOM testing primitives: scoped queries, event dispatch, async waiting
+- `@vielzeug/beacon`: Guided onboarding and contextual product tours for web applications
 - `@vielzeug/clockwork`: Framework-neutral finite state machines with pure transitions and actors
 - `@vielzeug/coins`: Currency formatting and exchange utilities for monetary arithmetic
 - `@vielzeug/conduit`: Typed dependency injection container