@adia-ai/a2ui-compose 0.0.1 → 0.2.0

package/strategies/zettel/state-cache.js

@@ -0,0 +1,153 @@
+/**
+ * State-cache — bounded LRU for multi-turn gen-UI compositions.
+ *
+ * Keyed by `state_id`. Bounded by `maxSize` (default 64; configurable via the
+ * `A2UI_STATE_CACHE_SIZE` env var). When the cache is at capacity, the
+ * least-recently-touched entry is evicted on the next `set`. Entries are
+ * touched on every `get` and on every overwriting `set`. `peek` reads without
+ * touching recency — used by the issue-reporter when attaching traces.
+ *
+ * Pure data structure: no I/O, no LLM, no async. Safe to instantiate as a
+ * server-process singleton; survives only as long as the MCP process.
+ *
+ * Recommended entry shape (caller-enforced — the cache itself stores any object):
+ *   {
+ *     state_id,            // mirrors the key
+ *     intent,              // user's request that produced this state
+ *     html,                // materialized output
+ *     plan,                // chunk-binding plan (or null for refinements)
+ *     ops_history,         // chronological A2UI message list
+ *     parent_state_id,     // chain-back for refinements (null for created roots)
+ *     created_at,          // ISO timestamp
+ *   }
+ *
+ * Spec: docs/specs/genui-multiturn-architecture.md §2.2 + §4.4.
+ */
+
+const DEFAULT_MAX_SIZE = 64;
+
+function envMaxSize() {
+  const v = process.env.A2UI_STATE_CACHE_SIZE;
+  if (!v) return null;
+  const n = parseInt(v, 10);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+export class StateCache {
+  constructor({ maxSize } = {}) {
+    this.maxSize = maxSize ?? envMaxSize() ?? DEFAULT_MAX_SIZE;
+    this._map = new Map();
+  }
+
+  /** Insert or update; touches recency. Returns the state_id. */
+  set(state_id, state) {
+    if (this._map.has(state_id)) {
+      this._map.delete(state_id);
+    } else if (this._map.size >= this.maxSize) {
+      const firstKey = this._map.keys().next().value;
+      this._map.delete(firstKey);
+    }
+    this._map.set(state_id, state);
+    return state_id;
+  }
+
+  /** Read; touches recency on hit. Returns null on miss. */
+  get(state_id) {
+    if (!this._map.has(state_id)) return null;
+    const entry = this._map.get(state_id);
+    this._map.delete(state_id);
+    this._map.set(state_id, entry);
+    return entry;
+  }
+
+  /** Read without touching recency. Returns null on miss. */
+  peek(state_id) {
+    return this._map.get(state_id) ?? null;
+  }
+
+  has(state_id) {
+    return this._map.has(state_id);
+  }
+
+  /** Returns true if removed, false if absent. */
+  evict(state_id) {
+    return this._map.delete(state_id);
+  }
+
+  /** Insertion-ordered list of keys (oldest → newest). */
+  list() {
+    return Array.from(this._map.keys());
+  }
+
+  size() {
+    return this._map.size;
+  }
+
+  clear() {
+    this._map.clear();
+  }
+}
+
+/**
+ * Mint a state_id for a freshly created composition.
+ *
+ * Format: `<intent-prefix>-<rand4>-v<N>-<unix-min>`
+ *  - intent-prefix — first whitespace-delimited word of the intent, lowercased,
+ *    non-alphanumeric stripped, capped at 12 chars; falls back to `state` when empty.
+ *  - rand4 — 4 hex chars; prevents collisions on identical intents.
+ *  - v<N> — 1-based version (v1 for created, v2+ for refinements).
+ *  - unix-min — Math.floor(Date.now() / 60000), giving a compact minute-resolution
+ *    timestamp that humans can scan for chronological order.
+ *
+ * Spec: docs/specs/genui-multiturn-architecture.md §2.2.
+ *
+ * @param {string} intent
+ * @param {number} [version=1]
+ * @returns {string}
+ */
+export function mintStateId(intent, version = 1) {
+  const prefix = (intent ?? '')
+    .toLowerCase()
+    .split(/\s+/)[0]
+    ?.replace(/[^a-z0-9]/g, '')
+    ?.slice(0, 12) || 'state';
+  const rand4 = Math.floor(Math.random() * 0xffff).toString(16).padStart(4, '0');
+  const unixMin = Math.floor(Date.now() / 60000);
+  const v = Math.max(1, Math.floor(version));
+  return `${prefix}-${rand4}-v${v}-${unixMin}`;
+}
+
+/**
+ * Mint the next state_id in a refinement chain.
+ *
+ * Preserves the parent's prefix + rand4 stem so the lineage is visible at a
+ * glance (`dash-3f9a-v1-…` → `dash-3f9a-v2-…`). Bumps the version and
+ * timestamp. Falls back to a fresh `mintStateId` if the parent id doesn't
+ * match the expected format.
+ *
+ * @param {string} parentStateId
+ * @param {number} version — should be parent's version + 1
+ * @returns {string}
+ */
+export function mintNextStateId(parentStateId, version) {
+  const m = parentStateId?.match(/^([a-z0-9]+)-([a-f0-9]{4})-v\d+-\d+$/);
+  if (!m) return mintStateId(parentStateId ?? '', version);
+  const [, prefix, rand4] = m;
+  const unixMin = Math.floor(Date.now() / 60000);
+  const v = Math.max(1, Math.floor(version));
+  return `${prefix}-${rand4}-v${v}-${unixMin}`;
+}
+
+let _cache = null;
+
+/** Module-level singleton. Lazily instantiated. */
+export function getStateCache(opts) {
+  if (!_cache) _cache = new StateCache(opts);
+  return _cache;
+}
+
+/** Replace the singleton; useful for tests + server boot. */
+export function resetStateCache(opts) {
+  _cache = new StateCache(opts);
+  return _cache;
+}

package/transpiler/transpiler.js

@@ -15,7 +15,7 @@ import {
   SKIP_TAGS, extractProps, inferGap,
 } from './transpiler-maps.js';
 import { validateSchema } from '../../validator/validator.js';
-import { getContext } from '../engine/reference.js';
+import { getContext } from '../core/reference.js';
 
 // ═══════════════════════════════════════════════════════════════
 // PUBLIC API

package/engine/constitution.md

@@ -1,78 +0,0 @@
-# AdiaUI Generation Constitution
-
-Rules the generator MUST satisfy. Used by the RLAIF critique-revise stage
-to evaluate and improve generated output. Each rule maps to a validator check.
-
----
-
-## Card Content Model
-
-- Every `Card` MUST have at least one of: `Header`, `Section`, `Footer`.
-- `Section` content MUST be wrapped in a `Column` component, not placed directly.
-- Headings (`h1`-`h6`) belong in `Header`, not `Section`.
-- Action buttons belong in `Footer`, not `Section` or `Header` (unless using `slot="action"`).
-- `Header` supports 4 slots: `slot="icon"` (leading), `slot="heading"` (title), `slot="description"` (subtitle), `slot="action"` (trailing badge/button).
-
-## Typography & Variant System
-
-- Use semantic HTML elements with `variant` attribute: `<h1 variant="title">`, `<h3 variant="section">`, `<p variant="body">`.
-- Never use `data-heading` — use `variant` instead.
-- Text hierarchy: display > title > heading > section > subsection > body > deck > caption > kicker > label.
-- Use `color="subtle"` or `color="muted"` for secondary text, not inline styles.
-
-## Layout Primitives
-
-- `Column` (col-ui): vertical stack. Use numeric `gap` values: `gap="2"`, `gap="4"`, `gap="6"`.
-- `Row` (row-ui): horizontal. Use `gap`, `justify`, `align` attributes.
-- `Grid` (grid-ui): CSS grid. Use `columns="2|3|4"`.
-- Never use named gaps (`gap="sm"`, `gap="md"`, `gap="lg"`) — always numeric.
-- Never use inline `style` attributes for layout.
-- Never use CSS class names.
-
-## Component Types
-
-- Use `Input` for text inputs (not `TextField` or `TextInput`).
-- Use `CheckBox` for checkboxes (not `Checkbox`).
-- Use `Select` for dropdowns (not `ChoicePicker`).
-- Use `Toggle` for switch controls.
-- Use `Button` with `variant="primary"` for main CTA, `variant="outline"` for secondary.
-- Button text via `text` prop, icon via `icon` prop (Phosphor icon name).
-
-## Flat Adjacency Protocol
-
-- Every component has a unique `id`.
-- Root component MUST have `id: "root"`.
-- Children referenced by ID array: `children: ["child-1", "child-2"]`.
-- IDs should be short and descriptive: `"hdr"`, `"email-field"`, `"submit-btn"`.
-- No circular references.
-- No orphaned components (every non-root must be referenced by a parent).
-
-## Anti-Patterns (DO NOT)
-
-1. **No bare divs** — never use `<div>` or HTML-only elements. Use AdiaUI components.
-2. **No flat adjacency violations** — every Text inside Section must be inside a Column wrapper.
-3. **No heading hierarchy skips** — don't jump from h1 to h3.
-4. **No duplicate IDs** — every component must have a unique ID.
-5. **No content directly in Tab** — Tab is a button strip item, not a content container.
-6. **No invented components** — only use types registered in the A2UI registry.
-7. **No slot on containers** — `slot="heading"` goes on the heading element, not on Header.
-8. **No inline styles** — use component props and tokens, not `style="..."`.
-
-## Prose & Content Context
-
-- For marketing/content pages, wrap in `<section prose>` to shift to content-optimized typography.
-- Centered page headers use: `<header align="center" size="lg">` → `<col-ui gap="4">` → kicker/display/deck.
-- Use `nomargin` on typography elements inside cards to prevent double-spacing.
-
-## Icon Names
-
-- Use Phosphor icon names: `arrow-right`, `check-circle`, `warning-circle`, etc.
-- Brand icons need `-logo` suffix: `google-logo`, `github-logo`, `twitter-logo`.
-- Common aliases are resolved automatically: `send`→`paper-plane-right`, `settings`→`gear`, `mail`→`envelope`.
-
-## Accessibility
-
-- Interactive elements must have `aria-label` if no visible text.
-- Icon-only buttons must have `aria-label`.
-- Images must have `alt` text.
-- Form inputs must have `label` prop.