golem-ui 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tony Lâmpada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,165 @@
+# golem-ui
+
+UI components with **one ABI**, built so an agent assembling a screen unattended gets it right the
+first time. Part of [Golem](https://github.com/tonylampada/golem-ui). MIT.
+
+**The site: https://tonylampada.github.io/golem-ui/** — the pitch, the quick start, and an index of
+everything below it:
+
+- **Showcase** (a demo app, for people, phone first): https://tonylampada.github.io/golem-ui/app/
+- **API pages** (the spec, phone first, readable signed out):
+  https://tonylampada.github.io/golem-ui/app/#/api
+- **Adapter pages** (the contract behind every `adapters` prop):
+  https://tonylampada.github.io/golem-ui/app/#/adapters
+- **Storybook** (every example as a live story, desktop):
+  https://tonylampada.github.io/golem-ui/storybook/
+
+## The ABI
+
+```tsx
+<Shell
+  config={{ title: 'Northgate Cycles', chatSide: 'left', breakpoint: 768, showTopBar: true }}
+  adapters={{ identity, navigation }}
+  chat={<AgentChat />}
+  canvas={<TodayScreen />}
+/>
+```
+
+- Every component has the same outer shape: `config` and `adapters`. No exceptions.
+- `config` is plain JSON-serializable data — what the component _is_. A Zod schema validates it on
+  mount; unknown fields are rejected.
+- Invalid config renders a **loud error card** naming the field and the rule, in dev and in prod.
+- `adapters` are how the component _talks to the world_: `Records`, `Files`, `Identity`, `Chat`,
+  `Clock`, `Navigation`. A component never imports a data layer, a router or a fetch.
+- `golem-ui` ships an in-memory fake of every adapter (`fakeIdentity()`, `fakeRecords()`, …). Stories
+  and tests run on the fakes; no backend, no network.
+- Config is **generated** by the agent, adapters are **wired** by the app. Two failure modes, kept
+  apart.
+- Docs are generated from the schema, so they cannot drift from the validator.
+
+## Adapters
+
+The adapters are the interface between a Golem app and the world, and that interface is the
+architecture. There are six, each documented as a thing in itself — every method, what an
+implementation has to guarantee, what it rejects with, and the in-memory fake — at
+[`#/adapters`](https://tonylampada.github.io/golem-ui/app/#/adapters) and under `Adapters/` in
+Storybook.
+
+| Adapter      | What it is                                                                                    |
+| ------------ | --------------------------------------------------------------------------------------------- |
+| `Records`    | Collections of JSON rows, the four writes, and the version check that keeps two writers apart |
+| `Files`      | A folder of blobs; refs are plain JSON and carry no bytes                                     |
+| `Identity`   | Who is here, how they got here, and who else may come in                                      |
+| `Chat`       | The conversation: history, send, and a stream that arrives token by token                     |
+| `Clock`      | Now and the zone to read it in, so nothing in the kit calls `new Date()`                      |
+| `Navigation` | The current route, `go(path)`, and a listener — no router imported anywhere                   |
+
+**One instance serves every component that takes it.** `Records` handed to a `RecordList` and to a
+`RecordForm` is what makes a ticket saved on one screen appear on the other; `subscribe` carries it,
+and neither component knows the other is there. The same goes for `Identity` across `Shell`, `Auth`,
+`RecordForm` and `Timeline`, and for `Files` across `Upload` and `Timeline`.
+
+## Adding an adapter
+
+1. `src/adapters/<name>.ts` — the interface, one doc comment per method, and any error class it
+   throws. Keep it minimal: cut what no component calls.
+2. `src/adapters/fake/<name>.ts` — the in-memory fake, real enough to run the failure path.
+3. `src/adapters/<name>.docs.ts` — the page's prose as data (`purpose`, every `method` with what it
+   guarantees and what it throws, `fake`, `consumers`). Add it to `adapterDocs` in `src/docs.ts`.
+4. `src/adapters/<Name>.mdx` — four lines: `<AdapterPage docs={...} links={storybookLinks} />`. The
+   showcase's `#/adapters/<name>` needs nothing; it reads the same list.
+5. Export the types from `src/adapters/index.ts` and the fake from `src/adapters/fake/index.ts`.
+
+`src/adapters/adapters.docs.test.ts` fails on an adapter with no `.docs.ts`, and on a `consumers`
+list that disagrees with what the components say they take.
+
+## Adding a component
+
+1. `src/components/<X>/<X>.config.ts` — the Zod schema, one `.describe()` per field, `.strict()`.
+2. `src/components/<X>/<X>.tsx` — a capitalised render function wrapped in `defineComponent`.
+   Adapters and slots go in interfaces beside it.
+3. `src/components/<X>/<X>.examples.tsx` — every example as data, adapters built once at module
+   scope. This file is the single source: stories and tests both import it.
+4. `src/components/<X>/<X>.stories.tsx` — one story per example, including an invalid-config one.
+5. `src/components/<X>/<X>.test.tsx` — renders every example, plus the seams worth holding.
+6. `src/components/<X>/<X>.docs.ts` — the page's prose as data (`tagline`, `purpose`, `adapters`,
+   `failureModes`, the example), and `<X>.mdx` reading it. Both the Storybook page and the API page
+   at `#/api/<x>` render that one object, so a sentence lives in one place. Copy `docs/TEMPLATE.md`
+   for the section order: it is fixed and no section is optional. Add the docs object to
+   `src/docs.ts`, and the component to `showcase/src/api-registry.tsx`.
+7. Export it from `src/index.ts`.
+8. Give it a place in the showcase: `showcase/README.md` names the screen it replaces, and that
+   screen is plain markup waiting for it. A component nobody can see working is not finished.
+
+A component that needs something new from the world extends an adapter rather than importing a data
+layer — and an adapter that gains a method gains a row on its own page in the same commit.
+
+`pnpm lint && pnpm typecheck && pnpm test && pnpm build && pnpm build-site && pnpm build-storybook &&
+pnpm build-showcase`
+
+## Install
+
+```sh
+npm i golem-ui react react-dom
+```
+
+React 19 is a peer dependency. Import the stylesheet once, at your app's entry:
+
+```tsx
+import { Shell, fakeIdentity, fakeNavigation } from 'golem-ui'
+import 'golem-ui/styles.css'
+
+const adapters = {
+  identity: fakeIdentity(),
+  navigation: fakeNavigation({ path: '/today', params: {} }),
+}
+
+export function App() {
+  return (
+    <Shell
+      config={{ title: 'Northgate Cycles' }}
+      adapters={adapters}
+      chat={<AgentChat />}
+      canvas={<TodayScreen />}
+    />
+  )
+}
+```
+
+In a TypeScript app, the `.css` import needs the ambient declaration Vite ships: keep
+`/// <reference types="vite/client" />` in `src/vite-env.d.ts`, as `npm create vite` writes it.
+
+`scripts/smoke-pack.sh` runs that install end to end — it packs the kit, installs the tarball into a
+throwaway Vite app outside the repo, and typechecks and builds it.
+
+## Releasing
+
+Every release after the first ships from GitHub Actions with npm [trusted
+publishing](https://docs.npmjs.com/trusted-publishers): the workflow mints its own short-lived
+credential from an OIDC token, so there is no `NPM_TOKEN` secret anywhere and the published tarball
+carries provenance.
+
+```sh
+# bump "version" in package.json and add the entry to CHANGELOG.md, then:
+git commit -am "Release 0.1.1"
+git tag v0.1.1
+git push origin main --tags
+```
+
+The tag starts `.github/workflows/release.yml`, which runs lint, typecheck, tests and the build,
+checks the tag matches `package.json`, and publishes. A tag whose version disagrees with
+`package.json` fails before the publish step.
+
+### The two one-time steps, for the captain
+
+1. **Publish 0.1.0 by hand**, from a shell logged in to npm. Trusted publishing is configured per
+   package, and the package has to exist first.
+
+   ```sh
+   npm login
+   pnpm build && npm publish --provenance --access public
+   ```
+
+2. **Turn on trusted publishing** at npmjs.com → the `golem-ui` package → Settings → Trusted
+   publishing → GitHub Actions, with organization/user `tonylampada`, repository `golem-ui`,
+   workflow `release.yml`, and no environment. From then on the tag is the whole release.

package/dist/abi/define-component.d.ts

@@ -0,0 +1,28 @@
+import { type FunctionComponent } from 'react';
+import type { z, ZodType } from 'zod';
+/**
+ * The outer shape of every golem-ui component, no exceptions.
+ *
+ * `Slots` carries the ReactNode holes a component exposes, plus the per-use props that belong to
+ * the call site rather than to the config — `Auth.Guard`'s `roles` is one. Anything the agent would
+ * write once for the whole app belongs in `config`, and anything that reaches the world in
+ * `adapters`.
+ */
+export type GolemProps<ConfigInput, Adapters, Slots = object> = {
+    config: ConfigInput;
+    adapters: Adapters;
+} & Slots;
+export interface ComponentSpec<Schema extends ZodType, Adapters, Slots = object> {
+    /** Shown in the error card, so it must be the name the agent writes in JSX. */
+    name: string;
+    schema: Schema;
+    render: FunctionComponent<GolemProps<z.output<Schema>, Adapters, Slots>>;
+}
+/**
+ * Wraps a renderer so the component validates its config before it renders anything, and shows a
+ * loud error card naming the field and the rule when validation fails.
+ */
+export declare function defineComponent<Schema extends ZodType, Adapters, Slots = object>(spec: ComponentSpec<Schema, Adapters, Slots>): FunctionComponent<GolemProps<z.input<Schema>, Adapters, Slots>> & {
+    schema: Schema;
+};
+//# sourceMappingURL=define-component.d.ts.map

package/dist/abi/define-component.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-component.d.ts","sourceRoot":"","sources":["../../src/abi/define-component.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,iBAAiB,EAAE,MAAM,OAAO,CAAA;AACvD,OAAO,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,KAAK,CAAA;AAGrC;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,CAAC,WAAW,EAAE,QAAQ,EAAE,KAAK,GAAG,MAAM,IAAI;IAC9D,MAAM,EAAE,WAAW,CAAA;IACnB,QAAQ,EAAE,QAAQ,CAAA;CACnB,GAAG,KAAK,CAAA;AAET,MAAM,WAAW,aAAa,CAAC,MAAM,SAAS,OAAO,EAAE,QAAQ,EAAE,KAAK,GAAG,MAAM;IAC7E,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,iBAAiB,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAA;CACzE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,SAAS,OAAO,EAAE,QAAQ,EAAE,KAAK,GAAG,MAAM,EAC9E,IAAI,EAAE,aAAa,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,GAC3C,iBAAiB,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAsBtF"}

package/dist/abi/docs.d.ts

@@ -0,0 +1,104 @@
+/**
+ * The prose a component page is made of, as data. Both consumers read this one object — the
+ * `.mdx` Storybook page and the showcase's phone-first `#/api` page — so a sentence exists once
+ * and neither surface can drift from the other.
+ *
+ * The generated parts of a page are not here: the configuration table is read off the Zod schema
+ * and the worked example is rendered from `<X>.examples.tsx`.
+ */
+export interface ComponentDocs {
+    /** As the component is exported and imported: `Shell`, `RecordList`. */
+    name: string;
+    /** The path segment under `#/api/`. */
+    slug: string;
+    /** Storybook's docs id for the component, e.g. `components-shell`. */
+    storybookPath: string;
+    /** One line, for a catalogue: what this component is, with no second sentence. */
+    tagline: string;
+    /** What it is for, and when to reach for something else. Markdown. */
+    purpose: string;
+    /** Anything the schema's own `.describe()` sentences cannot carry, in the order it reads. */
+    configNotes?: DocBlock[];
+    /** One row per adapter interface. An interface absent from here is one it never touches. */
+    adapters: AdapterRow[];
+    /** Rules about the adapters that are not per-method. Markdown. */
+    adapterNotes?: string;
+    /** Only for a component that takes slots. */
+    slots?: SlotRow[];
+    /** The complete config object as copy-pasteable TSX. */
+    example: string;
+    /** A markdown bullet list, each item opening with the bold name of the failure. */
+    failureModes: string;
+}
+/**
+ * A run of prose, or a table the prose around it refers to — the field-type vocabulary, for one.
+ * Markdown carries no tables, so a table is data and each surface draws it its own way.
+ */
+export type DocBlock = string | {
+    table: DocTable;
+};
+export interface DocTable {
+    headings: string[];
+    /** One array per row, in heading order. Cells are inline markdown. */
+    rows: string[][];
+}
+export interface AdapterRow {
+    /** The adapter interface, as it is named in `src/adapters/`. */
+    adapter: string;
+    /** The methods the component calls on it. */
+    calls: string;
+    /** Why it calls them. */
+    why: string;
+}
+export interface SlotRow {
+    slot: string;
+    what: string;
+}
+/**
+ * The prose an adapter page is made of, as data — the same arrangement `ComponentDocs` has, and
+ * for the same reason: the Storybook `Adapters/<Name>` page and the showcase's phone-first
+ * `#/adapters/<name>` page both render this one object, so a sentence exists once.
+ *
+ * An adapter has no Zod schema and no examples file, so nothing on its page is generated from
+ * code except `consumers`, which a test holds to what `componentDocs` actually says.
+ */
+export interface AdapterDocs {
+    /** The interface, as `src/adapters/` names it: `Records`, `Files`. */
+    name: string;
+    /** The file's basename in `src/adapters/`, and the path segment under `#/adapters/`. */
+    slug: string;
+    /** Storybook's docs id for the page, e.g. `adapters-records`. */
+    storybookPath: string;
+    /** One line, for a catalogue: what this adapter is, with no second sentence. */
+    tagline: string;
+    /** What the app is being asked for, and where the line between it and the component falls. */
+    purpose: string;
+    /** Every method on the interface, in the order the interface declares them. */
+    methods: AdapterMethod[];
+    /** Guarantees that span methods — error types, ordering, what a listener is promised. Markdown. */
+    notes?: string;
+    /** The in-memory fake, and how a story or a test reaches for it. */
+    fake: AdapterFake;
+    /**
+     * Every component that takes this adapter, by name. Read off each component's own adapter list
+     * rather than written here twice; a test fails when the two disagree.
+     */
+    consumers: string[];
+}
+export interface AdapterMethod {
+    /** The method as the interface declares it, parameter and return types included. */
+    signature: string;
+    /** What an implementation has to be true to. Markdown. */
+    guarantees: string;
+    /** What it rejects with, and when. Markdown. Absent on a method that cannot be refused. */
+    throws?: string;
+}
+export interface AdapterFake {
+    /** The exported factory: `fakeRecords`. */
+    name: string;
+    /** What it does that a real store does, and where it stops short. Markdown. */
+    what: string;
+    /** Building it and handing it to a component, as copy-pasteable TSX. */
+    example: string;
+}
+//# sourceMappingURL=docs.d.ts.map

package/dist/abi/docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/abi/docs.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAA;IACZ,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAA;IACZ,sEAAsE;IACtE,aAAa,EAAE,MAAM,CAAA;IACrB,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAA;IACf,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAA;IACf,6FAA6F;IAC7F,WAAW,CAAC,EAAE,QAAQ,EAAE,CAAA;IACxB,4FAA4F;IAC5F,QAAQ,EAAE,UAAU,EAAE,CAAA;IACtB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,OAAO,EAAE,CAAA;IACjB,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAA;IACf,mFAAmF;IACnF,YAAY,EAAE,MAAM,CAAA;CACrB;AAED;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG;IAAE,KAAK,EAAE,QAAQ,CAAA;CAAE,CAAA;AAEnD,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,sEAAsE;IACtE,IAAI,EAAE,MAAM,EAAE,EAAE,CAAA;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAA;IACf,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAA;IACb,yBAAyB;IACzB,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAA;IACZ,wFAAwF;IACxF,IAAI,EAAE,MAAM,CAAA;IACZ,iEAAiE;IACjE,aAAa,EAAE,MAAM,CAAA;IACrB,gFAAgF;IAChF,OAAO,EAAE,MAAM,CAAA;IACf,8FAA8F;IAC9F,OAAO,EAAE,MAAM,CAAA;IACf,+EAA+E;IAC/E,OAAO,EAAE,aAAa,EAAE,CAAA;IACxB,mGAAmG;IACnG,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,oEAAoE;IACpE,IAAI,EAAE,WAAW,CAAA;IACjB;;;OAGG;IACH,SAAS,EAAE,MAAM,EAAE,CAAA;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,oFAAoF;IACpF,SAAS,EAAE,MAAM,CAAA;IACjB,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAA;IAClB,2FAA2F;IAC3F,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAA;IACZ,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAA;IACZ,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAA;CAChB"}

package/dist/abi/error-card.d.ts

@@ -0,0 +1,18 @@
+import type { ZodError } from 'zod';
+export interface ConfigIssue {
+    /** Dotted path of the offending field, or `(root)` for the object itself. */
+    field: string;
+    /** The rule that rejected it, in Zod's own vocabulary. */
+    rule: string;
+    message: string;
+}
+export declare function issuesFromZodError(error: ZodError): ConfigIssue[];
+/**
+ * Rendered in place of the component whenever its config fails validation — in dev and in prod
+ * alike. A silent fallback would hide the mistake from the agent that made it.
+ */
+export declare function ConfigErrorCard({ component, issues, }: {
+    component: string;
+    issues: ConfigIssue[];
+}): import("react").JSX.Element;
+//# sourceMappingURL=error-card.d.ts.map

package/dist/abi/error-card.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-card.d.ts","sourceRoot":"","sources":["../../src/abi/error-card.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAA;AAEnC,MAAM,WAAW,WAAW;IAC1B,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAA;IACb,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,QAAQ,GAAG,WAAW,EAAE,CAMjE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,EAC9B,SAAS,EACT,MAAM,GACP,EAAE;IACD,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,WAAW,EAAE,CAAA;CACtB,+BAwBA"}

package/dist/abi/fields.d.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+/**
+ * The vocabulary an agent picks a field's `type` from, shared by every component configured with a
+ * list of fields. The type decides how a value is rendered, what `format` means, and — on a form —
+ * which control the reader gets. It never changes what the adapter returns or what is written back.
+ */
+export declare const FIELD_TYPES: readonly ["text", "number", "date", "datetime", "enum", "boolean", "money", "user"];
+export type FieldType = (typeof FIELD_TYPES)[number];
+/** A field as a list shows it: read-only, one column wide. */
+export declare const listFieldSchema: z.ZodObject<{
+    primary: z.ZodDefault<z.ZodBoolean>;
+    key: z.ZodString;
+    label: z.ZodString;
+    type: z.ZodEnum<{
+        number: "number";
+        boolean: "boolean";
+        text: "text";
+        date: "date";
+        datetime: "datetime";
+        enum: "enum";
+        money: "money";
+        user: "user";
+    }>;
+    format: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const fieldOptionSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+}, z.core.$strict>;
+/** A field as a form edits it: everything above, plus what makes a control out of it. */
+export declare const formFieldSchema: z.ZodObject<{
+    required: z.ZodDefault<z.ZodBoolean>;
+    readOnly: z.ZodDefault<z.ZodBoolean>;
+    help: z.ZodOptional<z.ZodString>;
+    placeholder: z.ZodOptional<z.ZodString>;
+    options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strict>>>;
+    min: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+    max: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+    multiline: z.ZodDefault<z.ZodBoolean>;
+    users: z.ZodDefault<z.ZodEnum<{
+        members: "members";
+        free: "free";
+    }>>;
+    key: z.ZodString;
+    label: z.ZodString;
+    type: z.ZodEnum<{
+        number: "number";
+        boolean: "boolean";
+        text: "text";
+        date: "date";
+        datetime: "datetime";
+        enum: "enum";
+        money: "money";
+        user: "user";
+    }>;
+    format: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type ListField = z.output<typeof listFieldSchema>;
+export type FormField = z.output<typeof formFieldSchema>;
+export type FieldOption = z.output<typeof fieldOptionSchema>;
+/** Whatever a records adapter hands back. `id` is the row key when there is one. */
+export type RecordRow = Record<string, unknown>;
+/** The part of a field that formatting reads. Both field shapes satisfy it. */
+export interface RenderedField {
+    type: FieldType;
+    format?: string;
+}
+//# sourceMappingURL=fields.d.ts.map

package/dist/abi/fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fields.d.ts","sourceRoot":"","sources":["../../src/abi/fields.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;GAIG;AACH,eAAO,MAAM,WAAW,qFASd,CAAA;AAEV,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAA;AA4BpD,8DAA8D;AAC9D,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;kBAUjB,CAAA;AAEX,eAAO,MAAM,iBAAiB;;;kBAKnB,CAAA;AAEX,yFAAyF;AACzF,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAmDjB,CAAA;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,eAAe,CAAC,CAAA;AACxD,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,eAAe,CAAC,CAAA;AACxD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAE5D,oFAAoF;AACpF,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAE/C,+EAA+E;AAC/E,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,SAAS,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB"}

package/dist/abi/index.d.ts

@@ -0,0 +1,8 @@
+export type { AdapterDocs, AdapterFake, AdapterMethod, AdapterRow, ComponentDocs, DocBlock, DocTable, SlotRow, } from './docs';
+export { defineComponent } from './define-component';
+export type { ComponentSpec, GolemProps } from './define-component';
+export { ConfigErrorCard, issuesFromZodError } from './error-card';
+export type { ConfigIssue } from './error-card';
+export { FIELD_TYPES, fieldOptionSchema, formFieldSchema, listFieldSchema } from './fields';
+export type { FieldOption, FieldType, FormField, ListField, RecordRow, RenderedField, } from './fields';
+//# sourceMappingURL=index.d.ts.map

package/dist/abi/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/abi/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,WAAW,EACX,WAAW,EACX,aAAa,EACb,UAAU,EACV,aAAa,EACb,QAAQ,EACR,QAAQ,EACR,OAAO,GACR,MAAM,QAAQ,CAAA;AACf,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AACpD,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AACnE,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAClE,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAC3F,YAAY,EACV,WAAW,EACX,SAAS,EACT,SAAS,EACT,SAAS,EACT,SAAS,EACT,aAAa,GACd,MAAM,UAAU,CAAA"}

package/dist/adapters/chat.d.ts

@@ -0,0 +1,28 @@
+import type { Unsubscribe } from './common';
+/** A file carried by a message, or staged in the composer. Name and size only — no bytes. */
+export interface ChatAttachment {
+    id: string;
+    name: string;
+    /** Bytes. Rendered on the chip as `12 KB`; omit it and the chip shows the name alone. */
+    size?: number;
+}
+export interface ChatMessage {
+    id: string;
+    role: 'user' | 'agent';
+    text: string;
+    at: string;
+    attachments?: ChatAttachment[];
+    /**
+     * True while the agent is still writing this message. The adapter emits the same `id` again and
+     * again with a longer `text`; the last emission of that id drops the flag, and that is `done`.
+     * An empty `text` with the flag set is the agent thinking before its first token.
+     */
+    streaming?: boolean;
+}
+export interface ChatAdapter {
+    history(): Promise<ChatMessage[]>;
+    send(text: string, attachments?: ChatAttachment[]): Promise<void>;
+    /** Called with the whole conversation on every change, including each token of a stream. */
+    subscribe(listener: (messages: ChatMessage[]) => void): Unsubscribe;
+}
+//# sourceMappingURL=chat.d.ts.map

package/dist/adapters/chat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.d.ts","sourceRoot":"","sources":["../../src/adapters/chat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAE3C,6FAA6F;AAC7F,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,yFAAyF;IACzF,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;IACtB,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,MAAM,CAAA;IACV,WAAW,CAAC,EAAE,cAAc,EAAE,CAAA;IAC9B;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,CAAA;IACjC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACjE,4FAA4F;IAC5F,SAAS,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,WAAW,EAAE,KAAK,IAAI,GAAG,WAAW,CAAA;CACpE"}

package/dist/adapters/chat.docs.d.ts

@@ -0,0 +1,3 @@
+import type { AdapterDocs } from '../abi';
+export declare const chatAdapterDocs: AdapterDocs;
+//# sourceMappingURL=chat.docs.d.ts.map

package/dist/adapters/chat.docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.docs.d.ts","sourceRoot":"","sources":["../../src/adapters/chat.docs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAA;AAEzC,eAAO,MAAM,eAAe,EAAE,WA0E7B,CAAA"}

package/dist/adapters/clock.d.ts

@@ -0,0 +1,5 @@
+export interface ClockAdapter {
+    now(): Date;
+    timeZone(): string;
+}
+//# sourceMappingURL=clock.d.ts.map

package/dist/adapters/clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../../src/adapters/clock.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAC3B,GAAG,IAAI,IAAI,CAAA;IACX,QAAQ,IAAI,MAAM,CAAA;CACnB"}

package/dist/adapters/clock.docs.d.ts

@@ -0,0 +1,3 @@
+import type { AdapterDocs } from '../abi';
+export declare const clockAdapterDocs: AdapterDocs;
+//# sourceMappingURL=clock.docs.d.ts.map

package/dist/adapters/clock.docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.docs.d.ts","sourceRoot":"","sources":["../../src/adapters/clock.docs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAA;AAEzC,eAAO,MAAM,gBAAgB,EAAE,WAgD9B,CAAA"}

package/dist/adapters/common.d.ts

@@ -0,0 +1,3 @@
+/** Every subscribe method returns one of these; calling it detaches the listener. */
+export type Unsubscribe = () => void;
+//# sourceMappingURL=common.d.ts.map

package/dist/adapters/common.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../src/adapters/common.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAA"}

package/dist/adapters/fake/chat.d.ts

@@ -0,0 +1,13 @@
+import type { ChatAdapter, ChatMessage } from '../chat';
+export interface FakeChatOptions {
+    /** Answered in order, one per send, looping when they run out. Empty means the agent stays mute. */
+    replies?: string[];
+    /** Milliseconds between tokens. Stories want it slow enough to watch, tests want it near zero. */
+    tokenDelayMs?: number;
+}
+/**
+ * The in-memory Chat adapter. `send` echoes the message, then streams the next canned reply word by
+ * word under one message id, so a component's streaming path is exercised without a backend.
+ */
+export declare function fakeChat(initial?: ChatMessage[], options?: FakeChatOptions): ChatAdapter;
+//# sourceMappingURL=chat.d.ts.map

package/dist/adapters/fake/chat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.d.ts","sourceRoot":"","sources":["../../../src/adapters/fake/chat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAkB,WAAW,EAAE,MAAM,SAAS,CAAA;AAGvE,MAAM,WAAW,eAAe;IAC9B,oGAAoG;IACpG,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,kGAAkG;IAClG,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAQD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,OAAO,GAAE,WAAW,EAAO,EAAE,OAAO,GAAE,eAAoB,GAAG,WAAW,CAsDhG"}

package/dist/adapters/fake/clock.d.ts

@@ -0,0 +1,4 @@
+import type { ClockAdapter } from '../clock';
+/** Frozen by default so time-based views render the same in every story and every test run. */
+export declare function fakeClock(fixed?: Date, timeZone?: string): ClockAdapter;
+//# sourceMappingURL=clock.d.ts.map

package/dist/adapters/fake/clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../../../src/adapters/fake/clock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAE5C,+FAA+F;AAC/F,wBAAgB,SAAS,CACvB,KAAK,GAAE,IAAuC,EAC9C,QAAQ,SAAQ,GACf,YAAY,CAKd"}

package/dist/adapters/fake/emitter.d.ts

@@ -0,0 +1,7 @@
+import type { Unsubscribe } from '../common';
+/** Shared listener bookkeeping for the fakes; not part of the public adapter surface. */
+export declare function createEmitter<T>(): {
+    subscribe(listener: (value: T) => void): Unsubscribe;
+    emit(value: T): void;
+};
+//# sourceMappingURL=emitter.d.ts.map

package/dist/adapters/fake/emitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitter.d.ts","sourceRoot":"","sources":["../../../src/adapters/fake/emitter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAE5C,yFAAyF;AACzF,wBAAgB,aAAa,CAAC,CAAC;wBAGP,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,WAAW;gBAIxC,CAAC;EAIhB"}

package/dist/adapters/fake/files.d.ts

@@ -0,0 +1,42 @@
+import { type FilesAdapter } from '../files';
+/**
+ * A file already in the store when the fake is built. `content` is what `url` hands back — a data
+ * URL for a seeded image — because the fake has no bytes of its own for a file nobody uploaded.
+ */
+export interface FakeFileSeed {
+    id?: string;
+    folder: string;
+    name: string;
+    contentType: string;
+    /** Bytes, for the tile. Defaults to the length of `content`. */
+    size?: number;
+    content?: string;
+    caption?: string;
+    /** A full ISO datetime. Defaults to the fake's `now`. */
+    uploadedAt?: string;
+}
+export interface FakeFilesOptions {
+    seed?: FakeFileSeed[];
+    /**
+     * `upload` rejects any file with exactly this name, so the error path has somewhere to be seen.
+     * Everything else in the same batch still goes up.
+     */
+    failOn?: string;
+    /** How long a fake upload takes end to end, in milliseconds. */
+    uploadMs?: number;
+    /** What stamps `uploadedAt`, so a test is not reading the wall clock. */
+    now?: () => Date;
+}
+/**
+ * A small stand-in picture, drawn rather than photographed: the fakes ship no image files, and a
+ * gallery with nothing in it teaches nothing. It is an SVG data URL, so it costs a few hundred
+ * bytes and needs no canvas, no network and no build step.
+ */
+export declare function placeholderImage(label: string, hue?: number): string;
+/**
+ * Files in memory: blobs behind object URLs, an upload that takes about 600 ms and says how far it
+ * has got, a canvas thumbnail for anything that is a picture, and one name it always refuses so the
+ * failure has a story of its own.
+ */
+export declare function fakeFiles(options?: FakeFilesOptions): FilesAdapter;
+//# sourceMappingURL=files.d.ts.map

package/dist/adapters/fake/files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../../src/adapters/fake/files.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,YAAY,EAElB,MAAM,UAAU,CAAA;AAGjB;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,gEAAgE;IAChE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,YAAY,EAAE,CAAA;IACrB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;CACjB;AAKD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,SAAM,GAAG,MAAM,CASjE;AAiED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,OAAO,GAAE,gBAAqB,GAAG,YAAY,CAiGtE"}

package/dist/adapters/fake/identity.d.ts

@@ -0,0 +1,24 @@
+import type { IdentityAdapter, User } from '../identity';
+export declare const fakeUser: User;
+export interface FakeIdentityOptions {
+    /** Who is signed in on mount. Omit and it is the first member; `null` starts the app signed out. */
+    user?: User | null;
+    /** The member table the list, invite and remove all work on. Defaults to `[fakeUser]`. */
+    members?: User[];
+    /** The one password every member accepts, so a demo can say it out loud. */
+    password?: string;
+    /** The one code `requestCode` always "sends". */
+    code?: string;
+    /** Role given to someone who signs up without an invite. */
+    defaultRole?: string;
+    /** What `invite()` prefixes the token with. The token is the last thing in the URL. */
+    inviteBase?: string;
+    /** Invites that already exist, token to role, so an example can open on a link nobody minted. */
+    invites?: Record<string, string>;
+}
+/**
+ * The in-memory Identity adapter: a member table, a signed-in user, and invite tokens that really
+ * round-trip — `invite()` hands back a URL whose token `signUp()` accepts exactly once.
+ */
+export declare function fakeIdentity(options?: FakeIdentityOptions): IdentityAdapter;
+//# sourceMappingURL=identity.d.ts.map

package/dist/adapters/fake/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../../src/adapters/fake/identity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAe,IAAI,EAAE,MAAM,aAAa,CAAA;AAGrE,eAAO,MAAM,QAAQ,EAAE,IAKtB,CAAA;AAED,MAAM,WAAW,mBAAmB;IAClC,oGAAoG;IACpG,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,CAAA;IAClB,0FAA0F;IAC1F,OAAO,CAAC,EAAE,IAAI,EAAE,CAAA;IAChB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,uFAAuF;IACvF,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,iGAAiG;IACjG,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACjC;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,eAAe,CA+F/E"}