aktion-runtime 0.5.11 → 0.5.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -24,7 +24,7 @@ That is the whole integration. Works in React, Vue, Angular, Svelte, plain
24
24
  HTML, or no framework at all.
25
25
 
26
26
  - **Docs site:** <https://asfand-dev.github.io/aktion/>
27
- - **Live examples:** <https://asfand-dev.github.io/aktion/live-examples.html>
27
+ - **Live demos:** <https://asfand-dev.github.io/aktion/live-demos.html>
28
28
  - **CDN bundle (ESM):** <https://asfand-dev.github.io/aktion/dist/aktion.js>
29
29
  - **System prompt (full):** <https://asfand-dev.github.io/aktion/dist/system_prompt.txt>
30
30
  - **System prompt (chat):** <https://asfand-dev.github.io/aktion/dist/system_prompt_chat.txt>
@@ -48,7 +48,7 @@ HTML, or no framework at all.
48
48
  - [Tooling](#tooling)
49
49
  - [Build-time compiler & multi-file modules](#build-time-compiler--multi-file-modules)
50
50
  - [Documentation site](#documentation-site)
51
- - [Live examples](#live-examples)
51
+ - [Live demos](#live-demos)
52
52
  - [Project layout](#project-layout)
53
53
  - [Run it locally](#run-it-locally)
54
54
  - [Security](#security)
@@ -154,7 +154,7 @@ Everything you need at runtime ships in a single bundle:
154
154
  `<details>.open`, and stateful primitives like `Tabs` are all preserved
155
155
  across renders. Components that need to hold UI state get a
156
156
  `helpers.useInstanceState(...)` slot keyed by their position in the tree.
157
- - **A rich component library** of **271 components** spanning layout,
157
+ - **A rich component library** of **275 components** spanning layout,
158
158
  forms, charts, data, feedback, navigation, patterns, app-shell composites,
159
159
  editors, advanced UI, motion, marketing, e-commerce, accessibility,
160
160
  realtime, and standard helpers. See [Component library](#component-library).
@@ -195,6 +195,15 @@ Everything you need at runtime ships in a single bundle:
195
195
  - **Markup escape hatches.** `HTMLTag(tag, { attributes?, children? })`
196
196
  and `Styles(css)` are the last-resort raw-HTML / raw-CSS injectors
197
197
  when no standard component captures the design.
198
+ - **Third-party widget interop.** `Mount({ setup, update?, cleanup?, props? })`
199
+ hosts an imperative library (chart, map, editor, payment element) with a
200
+ managed lifecycle; `WebComponent(tag, { attributes?, properties?, on? })`
201
+ bridges native custom elements; `$script({ src, global? })` loads an external
202
+ SDK once; and the `$dom` namespace gives auto-disposed resize / intersection /
203
+ mutation observers + `$dom.measure(node)`.
204
+ - **Document head & SEO.** `$head({ title, meta, og, twitter, link, jsonLd })`
205
+ is a reactive head manager — per-route titles / meta / Open Graph / JSON-LD
206
+ that also feed `renderToString` (`head` + `headAttrs`) for crawlable SSR.
198
207
  - **A system prompt generator.** Emits a clean, ordered prompt teaching
199
208
  the LLM exactly which components, builtins, and tools are available.
200
209
  Two flavours ship: `system_prompt.txt` (full — every feature) and
@@ -1038,7 +1047,7 @@ deep authoring guide [`coding-gen-skill.md`](./coding-gen-skill.md).
1038
1047
 
1039
1048
  ## Component library
1040
1049
 
1041
- The bundle ships **271 components** grouped by domain. Reach for **pattern composites**
1050
+ The bundle ships **275 components** grouped by domain. Reach for **pattern composites**
1042
1051
  (`Hero`, `PageHeader`, `Stats`, `Toolbar`, `EmptyState`, `Timeline`,
1043
1052
  `KanbanBoard`, `DescriptionList`, `PricingTable`, …) before hand-rolling
1044
1053
  the equivalent with `Card` + `Stack` — they're tuned to produce dense,
@@ -1071,6 +1080,7 @@ production-quality SaaS UI in a single line.
1071
1080
  | **Utility** | `SegmentedControl`, `FloatingActionButton`, `SpeedDial`, `BackToTop`, `VirtualGrid` (windowed 2-D grid) |
1072
1081
  | **Helpers** | `Async`, `Show`, `Portal`, `Redirect`, `Lazy`, `ErrorBoundary` |
1073
1082
  | **Behaviour wrappers** | `OnClick`, `OnMouse`, `OnKeyboard`, `OnFocus`, `OnIntersect`, `OnMount`, `Css`, `Link` — attach click / mouse / keyboard / focus / intersection / lifecycle listeners or raw class / style to ANY component without it needing a dedicated prop. `OnMount(child, { onMount, onUnmount })` is the DOM-ref escape hatch — `onMount(node)` fires once after attach so you can measure, focus, or hand the node to an imperative library. `Link(label_or_child, { to?, href?, external? })` wraps either a string or a component as a router-aware anchor. |
1083
+ | **Interop** | `Mount`, `WebComponent` — host an imperative / third-party widget (chart, map, editor, payment element) that owns its own DOM. `Mount({ setup, update?, cleanup?, props?, tag?, sx? })` gives a managed `setup → update → cleanup` lifecycle; `WebComponent(tag, { attributes?, properties?, on? })` renders + hydrates any native custom element with reactive attributes / events. Pair with the `$script({ src, global? })` loader and the `$dom` observer namespace — see [interop.html](https://asfand-dev.github.io/aktion/interop.html). |
1074
1084
  | **Escape hatches** | `HTMLTag`, `Styles` (last-resort raw HTML / CSS — see [language.html](https://asfand-dev.github.io/aktion/language.html#escape-hatches)) |
1075
1085
  | **Theming** | `$theme` |
1076
1086
  | **Routing** | `$router({ … })`, `NavLink` |
@@ -1548,7 +1558,16 @@ import {
1548
1558
  [playground](https://asfand-dev.github.io/aktion/playground.html)
1549
1559
  uses them under the hood. `getCompletions` is **scope-aware**: alongside
1550
1560
  the library + reserved words it surfaces the symbols declared in the
1551
- current document — your own reactive atoms, components, and actions.
1561
+ current document — your own reactive atoms, components, and actions. It is
1562
+ also **member-aware**: after a `.` it completes (and hovers / typechecks the
1563
+ signature of) every namespace member — `$util.*` (incl. nested `$util.style`
1564
+ / `$util.rules` / `$util.url`), `$storage.*`, `$console.*`, `$toast.*`, the
1565
+ `route` handle, and the resource bag a factory builtin returns (`$http`,
1566
+ `$query`, `$mutation`, `$socket`, `$sse`, `$form`, `$store`). Inside a
1567
+ config-taking builtin's object (`$http({ … })`, `$theme({ … })`, …) it
1568
+ completes and hovers the accepted config keys. The member + config catalog
1569
+ ships as data (`namespaceCatalog`, `factoryResourceCatalog`,
1570
+ `findBuiltinConfig`) so any host can reuse it.
1552
1571
 
1553
1572
  ### Migration & DX tooling
1554
1573
 
@@ -1689,6 +1708,8 @@ consumes from the CDN.
1689
1708
  | `components.html` | Every built-in component with a live preview, positional signatures, prop tables, and enum values. |
1690
1709
  | `actions.html` | `function name() { … }` guide — declarative state mutations, optimistic snapshot/rollback, lambda-based click handlers, navigation, and end-to-end examples. |
1691
1710
  | `side-effects.html` | `$effect(() => { … }, [...deps])` guide — anonymous side effects, dependency entries (state, lifecycle, intervals, debounce/throttle), top-level vs. component-local scope, cleanup, and effect vs. action. |
1711
+ | `interop.html` | Third-party / imperative widget interop — `Mount` (managed setup/update/cleanup lifecycle), `WebComponent` (native custom-element bridge), the `$script` external-SDK loader, and the `$dom` observer namespace. How `data-rui-preserve` keeps a widget's DOM intact. |
1712
+ | `head.html` | Document head & SEO — `$head({...})` for reactive title, meta, canonical/alternate links, Open Graph / Twitter cards, JSON-LD, and `<html>` attrs; per-route composition; and the SSR `head` / `headAttrs` output from `renderToString`. |
1692
1713
  | `javascript-interactions.html` | Effect + action bodies — the JavaScript execution surface. |
1693
1714
  | `routing.html` | Hash-based routing guide — always available at runtime. |
1694
1715
  | `reactivity.html` | Reactivity & rendering deep-dive — path tracking, the two render gates, exactly what forces a full re-render, and how to stay fine-grained. |
@@ -1696,40 +1717,41 @@ consumes from the CDN.
1696
1717
  | `troubleshooting.html` | Troubleshooting / FAQ — focus loss, effects not firing, memoized-away components, the `Map` component vs JS `Map`, dropped styles, missing i18n keys. |
1697
1718
  | `errors.html` | Error handling & debugging — reading parse/runtime errors, the render-loop and budget guards, the `error` event, and strict mode. |
1698
1719
  | `typescript.html` | TypeScript guide — public types, subpath entry points, typing custom components/helpers/interceptors, host event payloads, a typed host-wrapper recipe. |
1699
- | `recipes.html` | Recipes, patterns & anti-patterns — the A–V application patterns by task, the JS-aligned do/don't table, and the pre-ship self-check. |
1700
1720
  | `accessibility.html` | Accessibility guide — conformance target, keyboard map, screen-reader/streaming behaviour, built-in ARIA, and theme contrast. |
1701
1721
  | `deployment.html` | Production & deployment — SSR/hydration via `serializeState`, CSP and `unsafe-eval`, integrity hashes, CDN caching, edge-function LLM streaming. |
1702
1722
  | `llm-integration.html` | LLM integration — wiring OpenAI/Anthropic/OpenRouter/Bedrock streams into `appendChunk`, prompt selection, interceptors, the `assistant-message` round-trip. |
1703
1723
  | `themes.html` | Built-in themes gallery, live picker, side-by-side compare, and the token customization studio. |
1704
- | `examples.html` | Curated showcase of real-world block UIs (auth, products, FAQ, cart, todos, …). |
1724
+ | `theme-generator.html` | Visual theme generator — tune colors, radius, typography, spacing, shadows, and a brand gradient with a live preview, then copy a ready-to-paste `$theme({…})` statement. |
1705
1725
  | `playground.html` | CodeMirror 6 editor with custom highlighting / autocomplete, live preview, share links, hover-over component info, and an inspection mode. |
1706
1726
  | `visual-editor.html` | Drag-and-drop visual editor for the full 170+ component library. Three canvas modes (Raw Edit / Visual Edit / Preview), an Outline tab for top-level entity navigation, typed prop editors, cross-entity selection, and import / export of `.aktion` + self-contained HTML via an editable Source drawer. |
1707
1727
  | `chat-bot.html` | OpenRouter-powered streaming chat with four generation modes (Chat Compact, Chat Full, Website Builder, App Builder), image / PDF attachment support, and download-as-standalone-HTML. |
1708
- | `live-examples.html` | Catalog page that links every demo into the shared `live-example.html?example=<slug>` shell. |
1709
- | `live-example.html` | Shared shell for the bundled live examples — picks the demo from the `?example=<slug>` query parameter. |
1728
+ | `live-demos.html` | Catalog of every bundled demo program as zoomed-out live preview cards, sectioned by `docs/demos/` folder. |
1729
+ | `demos/index.html` | Shared runner shell for the bundled demos — picks the program from the `?app=<folder>/<file>.aktion` query parameter. |
1710
1730
 
1711
1731
  ---
1712
1732
 
1713
- ## Live examples
1733
+ ## Live demos
1714
1734
 
1715
- Every standalone demo is served by a single shell page
1716
- (`docs/live-example.html`) and a single JS bundle
1717
- (`docs/assets/live-example.js`) that ships every demo's Aktion source
1718
- and setup code together. Open any example with
1719
- `live-example.html?example=<slug>` — the shell renders the original
1720
- hero / source / output layout, so each demo doubles as an integration
1721
- recipe for `setResponse`, `appendChunk`, and `setTheme`.
1735
+ Every bundled demo is a pure `.aktion` program under `docs/demos/`,
1736
+ grouped by folder:
1722
1737
 
1723
- | Demo slug | Highlights |
1724
- | ------------------------------- | ----------------------------------------------------------------------------------------------------------- |
1725
- | `settings-app` | Tabs, `Switch`, `ToggleGroup`, `Progress`, `Kbd`, danger-zone confirmation `Drawer`. |
1726
- | `data-explorer` | Analytics surface: sortable `DataGrid` + bulk toolbar, `Gauge` SLA dials, `LineChart`, `Heatmap`, `RadarChart`, `ScatterChart`, `Histogram`, `InfiniteList`, `ActivityLog`. |
1727
- | `media-gallery` | Travel magazine: `Carousel` hero, `Gallery` + click-to-zoom `Lightbox`, `VideoPlayer`, `AudioPlayer`, Leaflet-backed `Map`. |
1728
- | `content-studio` | CMS-style authoring surface: `RichTextEditor`, `CodeEditor`, `MultiStepForm`, `ColorPicker`, `TagInput`, `MentionInput`, `PinInput`, `ValidationSummary`, `TopBar`. |
1729
- | `brand-themes.html` | Same UI reskinned with `$theme({...})` for **GitHub**, **Apple**, **Stripe**, **IONOS**, **Notion**, **Vercel** (bespoke UI on its own page). |
1738
+ | Folder | What's inside |
1739
+ | --------------------- | ------------------------------------------------------------------------------ |
1740
+ | `demos/mini-apps/` | Complete interactive apps — trackers, dashboards, storefronts, live-API browsers, marketing pages. |
1741
+ | `demos/blocks/` | Single-file, drop-in functional sections (login card, pricing plans, checkout form, …). |
1742
+ | `demos/components/` | Reusable `function` component showcases grouped by type (buttons, inputs, charts, …). |
1743
+ | `demos/industry-specific/` | Full per-industry surfaces with reusable building blocks (finance, healthcare, SaaS, e-commerce, AI, real estate, …). |
1730
1744
 
1731
- The full catalog with tag filters lives at
1732
- [`docs/live-examples.html`](https://asfand-dev.github.io/aktion/live-examples.html).
1745
+ All programs are served by one runner shell,
1746
+ `docs/demos/index.html?app=<folder>/<file>.aktion` (defaults to
1747
+ `mini-apps/aktion-website.aktion`), which also offers an app picker, a
1748
+ renderer-theme switcher, and a **View .aktion source** button that opens
1749
+ the program in the playground editor for live editing. The folder
1750
+ contents are scanned into `docs/demos/manifest.json` by
1751
+ `scripts/build-docs.mjs`.
1752
+
1753
+ The full catalog with zoomed-out live preview cards lives at
1754
+ [`docs/live-demos.html`](https://asfand-dev.github.io/aktion/live-demos.html).
1733
1755
 
1734
1756
  ---
1735
1757
 
@@ -1763,8 +1785,7 @@ The full catalog with tag filters lives at
1763
1785
  │ ├── element.ts # The custom element
1764
1786
  │ └── index.ts # Public entry point
1765
1787
  ├── docs/ # Static documentation site (HTML + CSS + JS)
1766
- │ ├── _examples/ # Author-facing source for every bundled live example
1767
- │ └── assets/live-example.js # GENERATED single-bundle for live-example.html
1788
+ │ └── demos/ # Bundled .aktion demo programs (mini-apps / blocks / components / industry-specific)
1768
1789
  ├── _docs/ # Internal design notes and inspirations (not shipped)
1769
1790
  ├── scripts/
1770
1791
  │ ├── emit-prompt.mjs # Writes dist/system_prompt*.txt from the bundle