@miakapp/cli 4.0.0-alpha.0 → 4.0.0-alpha.10

package/assets/design/guide.md

@@ -0,0 +1,77 @@
+# Designing a Miakapp home
+
+Miakapp gives you a starting point, not a framework: design tokens, four
+themes, a handful of CSS recipes and example screens. Take what helps, change
+anything, or make the home's own look with its residents. Nothing here is
+required by `miakapp check` or by the frame.
+
+## What ships with this CLI
+
+The files sit next to this guide, in the design directory printed at the end:
+
+| File | What it is |
+|---|---|
+| `tokens.css` | `--mk-*` variables (color, glass, radius, type, space, motion) for four themes |
+| `components.css` | Recipes on top of the tokens: glass, device tile, scene, switch, level slider, stale banner, tab bar |
+| `fonts.css` | Manrope as a `data:` URL, ready for the frame, which has no network (OFL, see `OFL-Manrope.txt`) |
+| `gallery.html` | Example screens built only with the files above: home, room, energy, wall tablet. Open it in a browser, switch themes, read its source |
+
+`miakapp init --starter app` writes all three stylesheets into `app/theme.ts`
+(`THEME_CSS`) and already uses them, so the first build looks like Miakapp.
+
+## Themes
+
+Set `data-theme` on `<html>` (or on any element, to theme one part):
+
+| Theme | Use |
+|---|---|
+| `minuit` | Night blue and gold from the Miakapp logo. Dark mode, wall tablets after dark. The house favourite. |
+| `lumiere` | Day. White glass over peach, mint and lilac. Light mode and the default. |
+| `miel` | Warm honey. Cosy, evening homes. |
+| `craie` | Flat, no blur, high contrast. Old or slow tablets, low vision. |
+
+Follow the resident: `home.theme()` is `light`, `dark` or `system`, and
+`home.onThemeChange()` tells you when it changes. The starter maps dark to
+Minuit and light to Lumière; a wall tablet may stay on Minuit.
+
+A home's own theme is one more `[data-theme="…"]` block redefining the same
+variables. Keep text contrast at 4.5:1 or more, including secondary text on
+glass; check dark themes twice (dark blue on darker blue is easy to miss).
+
+## Principles
+
+1. **The home first, not the devices.** Organize by room and by moment of the
+   day (evening, leaving, bedtime). Use the words residents use; never show a
+   state path or a device identifier.
+2. **What is on glows.** One strong signal per screen: the golden `--mk-on`
+   glow of a light, plug or scene that is on. Everything else stays calm.
+3. **One gradient per screen.** `--mk-accent-gradient` is a signature for one
+   title or one key number, not for every heading.
+4. **Say when the home goes quiet.** A stale value is dimmed (`is-stale`), a
+   banner says since when, controls are disabled. A command in flight shows
+   `is-pending` until the next state confirms it; an `outcome_unknown` call is
+   never retried.
+5. **Big fingers, little text.** 44 px targets at least, tabular digits, three
+   text sizes per screen. Phones, tablets on a wall and desktops all open the
+   same app: test at 360 px wide and at 1280 px.
+6. **Glass, but only two levels.** A glass panel may hold tiles; tiles do not
+   hold more glass. `craie` drops the blur entirely for weak devices.
+
+## The Miakapp bar is not yours
+
+Miakapp draws its own bar outside your frame: the home, the resident's other
+homes, their account and sign-in methods. Do not draw a global navigation that
+duplicates it (home switcher, profile, sign out). In-app navigation between
+your own screens (rooms, energy…) is yours; `gallery.html` shows where a
+home's own one or two entries would sit next to Miakapp's.
+
+## In the frame
+
+- No network: no web fonts, CDN stylesheets or remote images. Inline them as
+  `data:`/`blob:` URLs, like `fonts.css` does. The bundle limit is 2 MiB;
+  Manrope costs about 33 KB.
+- Respect `prefers-reduced-motion`; the tokens zero their durations for it.
+- `corner-shape: squircle` gives continuous corners where the browser supports
+  it; elsewhere the plain radius applies.
+- The bundle is public to signed-in users who know its digest: the gallery's
+  names are examples, real names come from state.

package/assets/design/tokens.css

@@ -0,0 +1,185 @@
+/*
+ * Miakapp design tokens — a starting palette for home interfaces.
+ *
+ * Copy it, rename it, change any value: it is yours. Four themes share the
+ * same variable names, so a screen written once works in all of them.
+ *   <html data-theme="lumiere">   day, glass on peach, mint and lilac (default)
+ *   <html data-theme="miel">      warm honey, cosy evenings
+ *   <html data-theme="minuit">    night blue and gold, wall tablets after dark
+ *   <html data-theme="craie">     flat and high-contrast, no blur: old tablets, accessibility
+ *
+ * The frame has no network: no web font is fetched. "Manrope" is used when the
+ * app bundles it as a data: URL; otherwise the system stack takes over.
+ */
+
+:root,
+[data-theme="lumiere"] {
+  color-scheme: light;
+
+  /* Canvas */
+  --mk-bg: #f6f3ee;
+  --mk-bg-art:
+    radial-gradient(60% 45% at 0% 0%, #ffd2b0 0%, transparent 70%),
+    radial-gradient(55% 45% at 100% 10%, #e3dcff 0%, transparent 70%),
+    radial-gradient(60% 50% at 80% 100%, #d6f5e3 0%, transparent 70%),
+    radial-gradient(40% 35% at 10% 90%, #ffe9a8 0%, transparent 70%);
+
+  /* Ink */
+  --mk-ink: #0a1024;
+  --mk-ink-2: rgb(10 16 36 / .62);
+  --mk-ink-3: rgb(10 16 36 / .40);
+  --mk-hairline: rgb(10 16 36 / .08);
+
+  /* Glass surfaces */
+  --mk-surface: linear-gradient(160deg, rgb(255 255 255 / .74), rgb(255 255 255 / .36));
+  --mk-surface-strong: rgb(255 255 255 / .86);
+  --mk-surface-sunken: rgb(10 16 36 / .05);
+  --mk-selected: rgb(255 255 255 / .9);
+  --mk-rim: rgb(255 255 255 / .8);
+  --mk-blur: 24px;
+  --mk-saturate: 1.8;
+  --mk-shadow: 0 1px 0 rgb(255 255 255 / .9) inset, 0 18px 40px -18px rgb(60 40 80 / .28);
+
+  /* Accent: titles, focus, the one thing that matters on a screen */
+  --mk-accent: #e0569b;
+  --mk-accent-gradient: linear-gradient(110deg, #ff7a45, #e0569b 55%, #7a5cff);
+
+  /* Something is on (a light, a plug, a scene running) */
+  --mk-on: linear-gradient(150deg, #ffe48a, #ffb547 70%, #ffa63b);
+  --mk-on-ink: #3a2300;
+  --mk-on-glow: 0 10px 30px -8px rgb(255 166 59 / .65);
+
+  /* Buttons */
+  --mk-button: #0a1024;
+  --mk-button-ink: #ffffff;
+
+  /* Meaning */
+  --mk-heat: #ff7a45;
+  --mk-cool: #5b8cff;
+  --mk-ok: #23a26d;
+  --mk-warn: #e58a12;
+  --mk-alert: #e5484d;
+}
+
+[data-theme="miel"] {
+  color-scheme: light;
+  --mk-bg: #fff6e8;
+  --mk-bg-art:
+    radial-gradient(60% 45% at 0% 0%, #ffe08a 0%, transparent 70%),
+    radial-gradient(50% 40% at 100% 20%, #ffc59a 0%, transparent 70%),
+    radial-gradient(60% 50% at 70% 100%, #ffd9c2 0%, transparent 70%);
+  --mk-ink: #1a1433;
+  --mk-ink-2: rgb(26 20 51 / .64);
+  --mk-ink-3: rgb(26 20 51 / .42);
+  --mk-hairline: rgb(26 20 51 / .09);
+  --mk-surface: linear-gradient(160deg, rgb(255 252 244 / .78), rgb(255 248 232 / .42));
+  --mk-surface-strong: rgb(255 252 244 / .9);
+  --mk-surface-sunken: rgb(26 20 51 / .06);
+  --mk-rim: rgb(255 255 255 / .75);
+  --mk-shadow: 0 1px 0 rgb(255 255 255 / .9) inset, 0 18px 40px -18px rgb(140 70 10 / .3);
+  --mk-accent: #ff7448;
+  --mk-accent-gradient: linear-gradient(110deg, #ffb41f, #ff9f2e 45%, #ff7448);
+  --mk-on: linear-gradient(150deg, #ffd45c, #ff9f2e 75%, #ff7448);
+  --mk-on-ink: #2a1300;
+  --mk-on-glow: 0 10px 30px -8px rgb(255 116 72 / .55);
+  --mk-button: #1a1433;
+  --mk-button-ink: #fff6e8;
+}
+
+[data-theme="minuit"] {
+  color-scheme: dark;
+  --mk-bg: #0a1024;
+  --mk-bg-art:
+    radial-gradient(70% 50% at 50% -10%, rgb(76 107 214 / .55) 0%, transparent 70%),
+    radial-gradient(50% 40% at 100% 100%, rgb(29 43 87 / .9) 0%, transparent 70%),
+    radial-gradient(40% 35% at 0% 80%, rgb(255 166 59 / .10) 0%, transparent 70%);
+  --mk-ink: #f4f1e8;
+  --mk-ink-2: rgb(244 241 232 / .76);
+  --mk-ink-3: rgb(244 241 232 / .58);
+  --mk-hairline: rgb(255 255 255 / .14);
+  --mk-surface: linear-gradient(160deg, rgb(255 255 255 / .16), rgb(255 255 255 / .07));
+  --mk-surface-strong: rgb(255 255 255 / .16);
+  --mk-surface-sunken: rgb(255 255 255 / .11);
+  --mk-selected: rgb(255 255 255 / .2);
+  --mk-rim: rgb(255 255 255 / .22);
+  --mk-saturate: 1.4;
+  --mk-shadow: 0 1px 0 rgb(255 255 255 / .12) inset, 0 20px 50px -20px rgb(0 0 0 / .7);
+  --mk-accent: #ffdd6e;
+  --mk-accent-gradient: linear-gradient(110deg, #fff1b8, #ffdd6e 40%, #ffa63b);
+  --mk-on: linear-gradient(150deg, #ffe48a, #ffa63b);
+  --mk-on-ink: #0a1024;
+  --mk-on-glow: 0 0 34px -6px rgb(255 190 80 / .6);
+  --mk-button: linear-gradient(150deg, #ffe48a, #ffa63b);
+  --mk-button-ink: #0a1024;
+  --mk-heat: #ff9a5c;
+  --mk-cool: #7ea2ff;
+  --mk-ok: #4fd39a;
+  --mk-warn: #ffbf47;
+  --mk-alert: #ff6b6f;
+}
+
+[data-theme="craie"] {
+  color-scheme: light;
+  --mk-bg: #eef0f3;
+  --mk-bg-art: none;
+  --mk-ink: #0d1117;
+  --mk-ink-2: #46505c;
+  --mk-ink-3: #6b7480;
+  --mk-hairline: #d6dbe1;
+  --mk-surface: #ffffff;
+  --mk-surface-strong: #ffffff;
+  --mk-surface-sunken: #e3e7ec;
+  --mk-selected: #e3e7ec;
+  --mk-rim: #d6dbe1;
+  --mk-blur: 0px;
+  --mk-saturate: 1;
+  --mk-shadow: 0 1px 2px rgb(13 17 23 / .08);
+  --mk-accent: #2457e6;
+  --mk-accent-gradient: linear-gradient(#0d1117, #0d1117);
+  --mk-on: #ffc533;
+  --mk-on-ink: #0d1117;
+  --mk-on-glow: none;
+  --mk-button: #0d1117;
+  --mk-button-ink: #ffffff;
+  --mk-ok: #12804f;
+  --mk-warn: #a85d00;
+  --mk-alert: #c4282d;
+}
+
+:root {
+  /* Type */
+  --mk-font: "Manrope", ui-rounded, "SF Pro Rounded", system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  --mk-text-xs: 12px;
+  --mk-text-sm: 13px;
+  --mk-text: 15px;
+  --mk-text-lg: 18px;
+  --mk-title: 24px;
+  --mk-display: 40px;
+  --mk-hero: 64px;
+  --mk-tight: -0.035em;
+
+  /* Shape: continuous corners where the browser supports them */
+  --mk-radius-sm: 12px;
+  --mk-radius: 22px;
+  --mk-radius-lg: 30px;
+  --mk-pill: 999px;
+
+  /* Space: 4 px steps */
+  --mk-1: 4px;
+  --mk-2: 8px;
+  --mk-3: 12px;
+  --mk-4: 16px;
+  --mk-5: 20px;
+  --mk-6: 24px;
+  --mk-8: 32px;
+
+  /* Motion */
+  --mk-ease: cubic-bezier(.2, .8, .2, 1);
+  --mk-spring: cubic-bezier(.34, 1.56, .64, 1);
+  --mk-fast: 140ms;
+  --mk-slow: 320ms;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :root { --mk-fast: 0ms; --mk-slow: 0ms; }
+}

package/assets/starter/app/app/README.md

@@ -0,0 +1,74 @@
+# This home's interface
+
+Written by `miakapp init --starter app`. It is a Miakapp **whole-house
+application** (`miakapp.app/1`): your own document, styles and navigation,
+bundled into one classic-script file that Miakapp runs in an isolated frame for
+the home's residents.
+
+```
+miakapp.yaml       home, control plane, artifact, and what the app may read and call
+package.json       build, typecheck and check scripts
+tsconfig.json      strict TypeScript for app/
+app/main.ts        the interface — edit this
+app/miakapp.ts     the bridge to the home (window.miakapp), copied from this CLI release
+app/theme.ts       Miakapp design tokens, themes and recipes (`miakapp docs design`): yours to change
+app/README.md      this file
+```
+
+Nothing here depends on an unpublished package or on the MiakAPI source
+repository.
+
+## Prerequisites
+
+- **Node.js ≥ 22.9** to run the `miakapp` CLI.
+- **Bun ≥ 1.2.23** to bundle `app/main.ts` (`bun build … --format=iife`). Any
+  bundler that emits one classic-script IIFE with no `import()` works too.
+- TypeScript only for `bun run typecheck` (`bun install` fetches it).
+
+## The loop
+
+```bash
+bun install            # the pinned @miakapp/cli and TypeScript, for the scripts below
+bun run build          # app/main.ts → the artifact named in miakapp.yaml
+bun run check          # build, then `miakapp check` validates it offline
+npx miakapp publish    # only once the interface is real (see below)
+npx miakapp status     # verify the digest you built is the one live
+```
+
+`npx miakapp` runs the CLI that `bun install` pinned in this project; a global
+`miakapp` works the same way.
+
+`publish` prints `home_url`: the address residents open. Open it as a member
+would and check it before handing it to anyone. The printed `artifact_url` is
+the raw bundle, never a link to give.
+
+## Before the first publication
+
+As generated, the app shows every value the home shares with it — grouped by
+the first segment of its path — and an honest empty state while nothing is
+shared. `app.requires` in `miakapp.yaml` starts empty, so the first build
+shows only that empty state. It invents no value and offers no control. That
+is a starting point, not a deliverable:
+
+1. **Inventory the house first** (`miakapp docs start`, §3): every source, what
+   each value means, how fresh it is, who may see it, which actions exist.
+2. **Declare what the app needs** under `app.requires.state_read` (exact paths
+   or `prefix.*`) and `app.requires.call`. The coordinator still decides per
+   resident; a path it does not share never reaches the app.
+3. **Make it a home, not a path list.** Fill `LABELS` with resident-facing
+   names, then replace the generic layout with one organized by room or use.
+   No technical vocabulary on screen.
+4. **Add controls only for actions the owner authorized.** Disable them while
+   `state.stale` is true. A call that fails with `outcome_unknown` may have
+   acted: never retry it, wait for the next state.
+
+## Rules the frame enforces
+
+- No network, no cookies or storage, no popups. Bundle images and fonts as
+  `data:`/`blob:` URLs. At most 2 MiB, no `import()`, no source map.
+- The bundle is public to signed-in users who know its digest: put no household
+  data in it. Read everything from state.
+- Never present stale values as current; never show a reading the home did not
+  send.
+- Do not edit `app/miakapp.ts`. It is the canonical bridge source shipped with
+  the CLI that generated it, so a newer CLI starter carries any change.

package/assets/starter/app/app/main.ts

@@ -0,0 +1,124 @@
+/**
+ * This home's interface: a Miakapp whole-house application (miakapp.app/1).
+ *
+ * A starting point, not a finished home. As written it shows exactly what the
+ * home shares with this interface — every granted state path, grouped by its
+ * first segment, with an honest notice when the view is stale — and nothing
+ * else: no invented value, no control. Before publishing it for residents:
+ *
+ * 1. inventory the house (sources, values, freshness, possible actions);
+ * 2. declare the paths and calls you need in miakapp.yaml (app.requires);
+ * 3. give every path a resident-facing name in LABELS, and replace this layout
+ *    with one organized the way people live in the house;
+ * 4. add controls only for calls the owner authorized, and never retry one
+ *    that failed with `outcome_unknown`.
+ *
+ * You own the whole document: any DOM, CSS, router or library a bundler can
+ * inline. `bun run build` emits one classic-script IIFE. The only way to the
+ * home is `./miakapp.ts`, the bridge copied from this CLI release.
+ *
+ * `./theme.ts` is the Miakapp design starting point (`miakapp docs design`):
+ * tokens, four themes and component recipes. Minuit follows the resident's
+ * dark mode, Lumière the light one. Keep it, restyle it or drop it.
+ */
+import { connect, type HomeState, type Theme } from './miakapp.js';
+import { THEME_CSS } from './theme.js';
+
+/** Resident-facing names, from your inventory. A path without one shows as the path. */
+const LABELS: Readonly<Record<string, string>> = {};
+
+const home = connect();
+const french = home.locale.toLowerCase().startsWith('fr');
+const TEXT = french
+  ? {
+    empty: 'Rien de cette maison n’est encore partagé avec cette interface.',
+    stale: 'Dernières valeurs connues ; en attente de la maison.',
+    yes: 'Oui',
+    no: 'Non',
+    missing: '—',
+  }
+  : {
+    empty: 'Nothing from this home is shared with this interface yet.',
+    stale: 'Showing the last known values; waiting for the home.',
+    yes: 'Yes',
+    no: 'No',
+    missing: '—',
+  };
+
+function element(tag: string, text?: string, className?: string): HTMLElement {
+  const node = document.createElement(tag);
+  if (text !== undefined) node.textContent = text;
+  if (className !== undefined) node.className = className;
+  return node;
+}
+
+const style = document.createElement('style');
+style.textContent = `${THEME_CSS}
+  body { margin: 0; min-height: 100vh; }
+  h1 { margin: 0; padding: 28px 20px 4px; }
+  main { display: grid; gap: 14px; grid-template-columns: repeat(auto-fit, minmax(240px, 1fr)); padding: 16px; }
+  section { padding: 18px; }
+  h2 { margin: 0 0 10px; font-size: var(--mk-text-lg); font-weight: 800; text-transform: capitalize; }
+  dl { margin: 0; display: grid; grid-template-columns: 1fr auto; gap: 8px 12px; }
+  dt { color: var(--mk-ink-2); }
+  dd { margin: 0; font-weight: 700; text-align: end; }
+  .mk-stale-banner { margin: 8px 16px 0; }
+  .empty { padding: 0 20px; color: var(--mk-ink-2); }
+  .is-stale dd { opacity: .55; }
+`;
+document.head.append(style);
+
+/** The resident's light or dark preference picks the theme; "system" asks the browser. */
+function applyTheme(preference: Theme): void {
+  const dark = preference === 'dark' || (preference === 'system'
+    && typeof matchMedia === 'function' && matchMedia('(prefers-color-scheme: dark)').matches);
+  document.documentElement.dataset['theme'] = dark ? 'minuit' : 'lumiere';
+}
+applyTheme(home.theme());
+home.onThemeChange(applyTheme);
+if (typeof matchMedia === 'function') {
+  matchMedia('(prefers-color-scheme: dark)').addEventListener('change', () => applyTheme(home.theme()));
+}
+document.body.className = 'mk-app';
+
+const title = element('h1', undefined, 'mk-display');
+const notice = document.createElement('p');
+const main = document.createElement('main');
+document.body.append(title, notice, main);
+
+function format(value: unknown): string {
+  if (value === undefined || value === null) return TEXT.missing;
+  if (typeof value === 'boolean') return value ? TEXT.yes : TEXT.no;
+  if (typeof value === 'number') return Number.isFinite(value) ? value.toLocaleString(home.locale) : TEXT.missing;
+  if (typeof value === 'string') return value;
+  return JSON.stringify(value);
+}
+
+function render(state: HomeState): void {
+  title.textContent = home.name;
+  notice.className = state.stale ? 'mk-stale-banner' : '';
+  notice.textContent = state.stale ? TEXT.stale : '';
+
+  const paths = home.paths();
+  if (paths.length === 0) {
+    main.replaceChildren(element('p', TEXT.empty, 'empty'));
+    return;
+  }
+  const groups = new Map<string, string[]>();
+  for (const path of paths) {
+    const group = path.split('.')[0] ?? path;
+    groups.set(group, [...groups.get(group) ?? [], path]);
+  }
+  main.replaceChildren(...[...groups].map(([group, members]) => {
+    const section = element('section', undefined, state.stale ? 'mk-glass is-stale' : 'mk-glass');
+    const list = element('dl');
+    for (const path of members) {
+      list.append(element('dt', LABELS[path] ?? path), element('dd', format(state.values[path])));
+    }
+    section.append(element('h2', group), list);
+    return section;
+  }));
+}
+
+home.subscribe(render);
+home.ready();

package/assets/starter/app/app/miakapp.ts

@@ -0,0 +1,156 @@
+/**
+ * Typed access to a Miakapp whole-house application's one window on its home.
+ *
+ * A `miakapp.app/1` release is a single classic-script bundle that owns its
+ * whole document: any DOM, CSS, router or UI library. It runs in an isolated
+ * opaque-origin frame with no network and no storage, and the trusted shell
+ * installs exactly one object before the bundle runs: `window.miakapp`. This
+ * package types that object and adds the few helpers every house needs, so a
+ * house reads state and calls functions without reaching for `any`.
+ *
+ * Nothing here grants anything. What the house may read and call is its
+ * release's `requires`, narrowed by the coordinator per resident; a path the
+ * resident may not see never reaches the frame.
+ */
+
+export const APP_ABI = 'miakapp.app/1' as const;
+
+export const CALL_ERROR_CODES = [
+  'denied',
+  'unavailable',
+  'failed',
+  'outcome_unknown',
+  'timeout',
+  'busy',
+] as const;
+
+/**
+ * Why a call did not complete. `outcome_unknown` means the home may have acted:
+ * never retry it, wait for the next state instead.
+ */
+export type CallErrorCode = (typeof CALL_ERROR_CODES)[number];
+
+export type Theme = 'system' | 'light' | 'dark';
+
+export interface HomeState {
+  readonly values: Readonly<Record<string, unknown>>;
+  readonly revision: number;
+  /** True when Miakapp no longer has a current view: show it, never hide it. */
+  readonly stale: boolean;
+}
+
+/** The object the trusted shell installs as `window.miakapp`. */
+export interface MiakappHost {
+  readonly abi: typeof APP_ABI;
+  readonly release: string;
+  readonly home: { readonly id: string; readonly name: string };
+  readonly locale: string;
+  readonly theme: string;
+  onThemeChange(listener: (theme: string) => void): () => void;
+  readonly state: {
+    get(path: string): unknown;
+    values(): Readonly<Record<string, unknown>>;
+    readonly revision: number;
+    readonly stale: boolean;
+    subscribe(listener: (state: HomeState) => void): () => void;
+  };
+  readonly can: { read(path: string): boolean; call(name: string): boolean };
+  call(name: string, args?: unknown, options?: { timeoutMs?: number }): Promise<unknown>;
+  ready(): void;
+}
+
+export class MiakappUnavailableError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'MiakappUnavailableError';
+  }
+}
+
+export interface Home {
+  readonly id: string;
+  readonly name: string;
+  readonly release: string;
+  /** BCP 47 language of the resident, e.g. `fr`. */
+  readonly locale: string;
+  theme(): Theme;
+  onThemeChange(listener: (theme: Theme) => void): () => void;
+  /** The current granted view, immutable. */
+  state(): HomeState;
+  get<T = unknown>(path: string): T | undefined;
+  /** Granted paths, optionally under one dotted prefix, sorted. */
+  paths(prefix?: string): string[];
+  /**
+   * Calls `listener` with every new view. With `immediate` (the default) it is
+   * also called once now, so a render function can be the only listener.
+   */
+  subscribe(listener: (state: HomeState) => void, options?: { immediate?: boolean }): () => void;
+  canRead(path: string): boolean;
+  canCall(name: string): boolean;
+  /** Rejects with an error whose `callErrorCode()` is one of `CALL_ERROR_CODES`. */
+  call<T = unknown>(name: string, args?: unknown, options?: { timeoutMs?: number }): Promise<T>;
+  /** Lifts the shell's loading screen before the script finishes, if you want. */
+  ready(): void;
+}
+
+function theme(value: string): Theme {
+  return value === 'light' || value === 'dark' ? value : 'system';
+}
+
+function isHost(value: unknown): value is MiakappHost {
+  if (value === null || typeof value !== 'object') return false;
+  const candidate = value as Partial<MiakappHost>;
+  return candidate.abi === APP_ABI
+    && typeof candidate.call === 'function'
+    && typeof candidate.state === 'object'
+    && typeof candidate.state?.subscribe === 'function';
+}
+
+/**
+ * Connects to the home this frame was opened for. Throws when not running
+ * inside a Miakapp house frame — for example in a unit test or a plain browser
+ * tab — so a mistake fails loudly instead of rendering an empty home.
+ */
+export function connect(scope: { readonly miakapp?: unknown } = globalThis as { miakapp?: unknown }): Home {
+  const host = scope.miakapp;
+  if (!isHost(host)) {
+    throw new MiakappUnavailableError(
+      'window.miakapp is missing: this bundle runs only inside a Miakapp house frame',
+    );
+  }
+  const snapshot = (): HomeState => ({
+    values: host.state.values(),
+    revision: host.state.revision,
+    stale: host.state.stale,
+  });
+  return Object.freeze({
+    id: host.home.id,
+    name: host.home.name,
+    release: host.release,
+    locale: host.locale,
+    theme: () => theme(host.theme),
+    onThemeChange: (listener: (value: Theme) => void) => host.onThemeChange((value) => listener(theme(value))),
+    state: snapshot,
+    get: <T>(path: string) => host.state.get(path) as T | undefined,
+    paths: (prefix?: string) => Object.keys(host.state.values())
+      .filter((path) => prefix === undefined || path === prefix || path.startsWith(`${prefix}.`))
+      .sort(),
+    subscribe: (listener: (state: HomeState) => void, options: { immediate?: boolean } = {}) => {
+      const unsubscribe = host.state.subscribe(listener);
+      if (options.immediate ?? true) listener(snapshot());
+      return unsubscribe;
+    },
+    canRead: (path: string) => host.can.read(path),
+    canCall: (name: string) => host.can.call(name),
+    call: async <T>(name: string, args?: unknown, options?: { timeoutMs?: number }) => (
+      await host.call(name, args ?? null, options ?? {}) as T
+    ),
+    ready: () => host.ready(),
+  });
+}
+
+/** The closed reason a call failed, or undefined for anything else. */
+export function callErrorCode(error: unknown): CallErrorCode | undefined {
+  if (error === null || typeof error !== 'object' || !('code' in error)) return undefined;
+  const code = (error as { code: unknown }).code;
+  return (CALL_ERROR_CODES as readonly unknown[]).includes(code) ? code as CallErrorCode : undefined;
+}