@hanzo/rooms 0.1.0

package/dist/failure.d.ts

@@ -0,0 +1,57 @@
+/** Whether the store answered and the answer was no — exported so a surface can
+ *  offer the way past a refusal rather than only describing it. */
+export declare const refused: (error: unknown) => boolean;
+/**
+ * A sentence about `subject` — "your drive", "this board" — naming what a
+ * reader can do next. Never the caught text: an error written for an operator
+ * is not an answer for a reader.
+ */
+export declare function say(error: unknown, subject: string, act?: 'read' | 'save'): string;
+/**
+ * The reader's version of a failure, keeping what the store said when that is
+ * an answer.
+ *
+ * A gateway that refuses over credit, a context that ran long, a model nobody
+ * serves — each of those is the reader's own situation, stated by the only
+ * thing that knows it, and translating them away would leave a room saying
+ * nothing where it could have said the one useful thing. A gateway that is not
+ * there, or one that refused the account, is the estate talking to itself; that
+ * half is replaced.
+ */
+export declare function plainly(error: unknown, subject: string): string;
+/**
+ * Whether a refusal asks for a plan, and the checkout it names.
+ *
+ * The gateway refuses a model the plan does not include with 402
+ * `plan_required`, a Free caller whose share is spent with 402
+ * `allowance_spent`, and a free request the shared pool cannot serve with 429
+ * `pool_busy` or `pool_exhausted`, each with an `upgrade_url`. The code decides,
+ * never the sentence. The address is kept only when it is an https page on
+ * hanzo.ai or one of its hosts; any other leaves `href` empty and the caller
+ * builds its own.
+ */
+export declare function planRequired(error: unknown): {
+    href?: string;
+} | null;
+/** A plan holder's spent window. */
+export interface Cap {
+    limit: 'session' | 'day';
+    /** When it opens again, RFC 3339. */
+    resets: string | null;
+    /** The next plan's checkout, on hanzo.ai only. Absent at the top plan. */
+    href?: string;
+}
+/**
+ * Whether a refusal is a plan's usage limit, and which window.
+ *
+ * A paid plan is a subscription with limits: a spent session or day comes back
+ * 429 `usage_cap_exceeded` naming the window, its reset and, below the top
+ * plan, an `upgrade_url`. The month refuses nothing — Enso and Zen keep
+ * answering — so no other window is a cap. The code decides, never the
+ * sentence, and the address is kept by the rule `planRequired` keeps.
+ */
+export declare function capped(error: unknown): Cap | null;
+/** The family a model id belongs to, as a reader knows it, or '' for one outside them. */
+export declare const familyOf: (id: string) => string;
+/** What the server said about a failure, for the detail folded under the plain line. */
+export declare const detail: (error: unknown) => string;

package/dist/failure.js

@@ -0,0 +1,143 @@
+'use client';
+// What to tell a reader when a room's store does not answer.
+//
+// The rooms used to print the error they caught, which on a store that is down
+// reads "mount /v1/s3: no instance running". That says nothing a reader can act
+// on — it names a mount and an instance, neither of which is theirs — and it
+// puts the shape of the estate on a public page. The detail is still in the
+// network tab, where the person who can act on it is looking.
+//
+// ONE FUNCTION, because every room owes the same three answers and three copies
+// would drift into three vocabularies for one event.
+import { told } from './lib/reach.js';
+/**
+ * THE STATUS, WHERE THE FAILURE CARRIES ONE.
+ *
+ * `@hanzo/ai`'s APIError publishes `status` as a number, and a number is a fact
+ * — while the message beside it is prose the SDK is free to improve. It did:
+ * 0.6.16 added a table answering 503 with "The service is not running right
+ * now.", which reads the same to a person and matches none of the patterns
+ * below, so every downed store fell through to the flat "Could not read" and
+ * the rooms stopped saying that nothing had been lost. Reading the status first
+ * is what makes this survive the next rewording.
+ */
+const status = (e) => {
+    const s = e?.status;
+    return typeof s === 'number' && Number.isFinite(s) ? s : null;
+};
+/** True where a failure is the store being absent rather than the reader. The
+ *  text is still read, because a network failure raises before any status. */
+const absent = (text) => /no instance running|not running|service unavailable|503|econnrefused|failed to fetch|network/i.test(text);
+/**
+ * True where the answer was no, whoever said it.
+ *
+ * Three vocabularies for one event. The gateway says 401 "authentication
+ * required" on a turn and 403 "a validated principal is required" on a read,
+ * and the SDK raises before sending at all when it has no credential to send
+ * with. A reader meets the same wall in every case, so all three read as one.
+ */
+const barred = (text) => /401|403|forbidden|unauthori[sz]ed|not authori[sz]ed|authentication required|validated principal|permission|serve anonymous|anonymous completions/i.test(text);
+/** Whether the store answered and the answer was no — exported so a surface can
+ *  offer the way past a refusal rather than only describing it. */
+export const refused = (error) => {
+    const code = status(error);
+    if (code === 401 || code === 403)
+        return true;
+    return barred(error instanceof Error ? error.message : String(error ?? ''));
+};
+/**
+ * A sentence about `subject` — "your drive", "this board" — naming what a
+ * reader can do next. Never the caught text: an error written for an operator
+ * is not an answer for a reader.
+ */
+export function say(error, subject, act = 'read') {
+    const text = error instanceof Error ? error.message : String(error ?? '');
+    const code = status(error);
+    // VERB FIRST, so the subject's number never has to agree with anything. Said
+    // subject-first, "your projects is not answering" is what a plural name gets,
+    // and every caller then has to remember to phrase its subject singular.
+    if (code === 502 || code === 503 || code === 504 || absent(text))
+        return `Could not reach ${subject}. Nothing has been lost — try again shortly.`;
+    if (code === 401 || code === 403 || barred(text))
+        return act === 'save'
+            ? `This account cannot change ${subject}.`
+            : `This account cannot open ${subject}.`;
+    return act === 'save' ? `Could not save ${subject}.` : `Could not read ${subject}.`;
+}
+/**
+ * The reader's version of a failure, keeping what the store said when that is
+ * an answer.
+ *
+ * A gateway that refuses over credit, a context that ran long, a model nobody
+ * serves — each of those is the reader's own situation, stated by the only
+ * thing that knows it, and translating them away would leave a room saying
+ * nothing where it could have said the one useful thing. A gateway that is not
+ * there, or one that refused the account, is the estate talking to itself; that
+ * half is replaced.
+ */
+export function plainly(error, subject) {
+    const text = error instanceof Error ? error.message : String(error ?? '');
+    return absent(text) || barred(text) ? say(error, subject) : told(error) ?? text;
+}
+/**
+ * The refusals a plan lifts, by the status each arrives with: a model the plan
+ * does not include, and the Free plan's two limits — a person's own share of
+ * the pool spent for the window, and the pool every free user shares used up.
+ */
+const LIFTED = {
+    plan_required: 402,
+    allowance_spent: 402,
+    pool_busy: 429,
+    pool_exhausted: 429,
+};
+/**
+ * Whether a refusal asks for a plan, and the checkout it names.
+ *
+ * The gateway refuses a model the plan does not include with 402
+ * `plan_required`, a Free caller whose share is spent with 402
+ * `allowance_spent`, and a free request the shared pool cannot serve with 429
+ * `pool_busy` or `pool_exhausted`, each with an `upgrade_url`. The code decides,
+ * never the sentence. The address is kept only when it is an https page on
+ * hanzo.ai or one of its hosts; any other leaves `href` empty and the caller
+ * builds its own.
+ */
+export function planRequired(error) {
+    const said = error?.body?.error;
+    const code = typeof said?.code === 'string' ? said.code : '';
+    if (!LIFTED[code] || status(error) !== LIFTED[code])
+        return null;
+    return { href: ours(said?.upgrade_url) };
+}
+/**
+ * Whether a refusal is a plan's usage limit, and which window.
+ *
+ * A paid plan is a subscription with limits: a spent session or day comes back
+ * 429 `usage_cap_exceeded` naming the window, its reset and, below the top
+ * plan, an `upgrade_url`. The month refuses nothing — Enso and Zen keep
+ * answering — so no other window is a cap. The code decides, never the
+ * sentence, and the address is kept by the rule `planRequired` keeps.
+ */
+export function capped(error) {
+    const said = error?.body?.error;
+    if (said?.code !== 'usage_cap_exceeded' || status(error) !== 429)
+        return null;
+    if (said.limit !== 'session' && said.limit !== 'day')
+        return null;
+    return { limit: said.limit, resets: typeof said.resets_at === 'string' ? said.resets_at : null, href: ours(said.upgrade_url) };
+}
+function ours(href) {
+    if (typeof href !== 'string')
+        return undefined;
+    try {
+        const url = new URL(href);
+        const host = url.hostname;
+        return url.protocol === 'https:' && (host === 'hanzo.ai' || host.endsWith('.hanzo.ai')) ? url.toString() : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The family a model id belongs to, as a reader knows it, or '' for one outside them. */
+export const familyOf = (id) => /^(hanzo\/)?enso/i.test(id) ? 'Enso' : /^(hanzo\/)?zen/i.test(id) ? 'Zen' : '';
+/** What the server said about a failure, for the detail folded under the plain line. */
+export const detail = (error) => told(error) ?? (error instanceof Error ? error.message : String(error ?? ''));

package/dist/ground.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The ground the workspace's cards stand on, and how each card is cut.
+ *
+ * A PANE is a card floating on the ground, cut by the `--pane-*` tokens
+ * (app/globals.css): a corner, an edge, the lens behind it, and the second
+ * paper rung's lit edge and drop. The fill is the caller's rung: `--pane-fill`
+ * in the app's frame, `sheet(1)`/`sheet(2)` where a pane lies in a room.
+ *
+ * The drop is a prop and not `sheet(2)`'s `elevation-2` class, whose shadow is
+ * `!important`: a Dev run's pane steps aside for the two panes inside it by
+ * slot (@hanzo/build's `run-split`), and an important shadow would stay behind.
+ */
+export declare const pane: (fill?: string) => {
+    readonly backgroundColor: string;
+    readonly borderRadius: 'var(--pane-round)';
+    readonly borderWidth: 1;
+    readonly borderColor: 'var(--pane-edge)';
+    readonly backdropFilter: 'var(--pane-blur)';
+    readonly boxShadow: 'var(--shadow-sheet-2)';
+};
+/**
+ * THE FLOOR under the app's frame (app/_web.tsx, components/settings/Frame.tsx):
+ * design's top light falling off down the window over the faint lamps of
+ * `--pane-ground`. A straight fall rather than a radial glow, because at these
+ * alphas a circle quantises into rings a blur makes plainer.
+ */
+export declare const floor: {
+    readonly backgroundColor: 'var(--pane-floor)';
+    readonly backgroundImage: 'linear-gradient(to bottom, var(--glass-strong), transparent), var(--pane-ground)';
+    readonly backgroundSize: '100% 70%, auto';
+    readonly backgroundRepeat: 'no-repeat';
+};

package/dist/ground.js

@@ -0,0 +1,32 @@
+/**
+ * The ground the workspace's cards stand on, and how each card is cut.
+ *
+ * A PANE is a card floating on the ground, cut by the `--pane-*` tokens
+ * (app/globals.css): a corner, an edge, the lens behind it, and the second
+ * paper rung's lit edge and drop. The fill is the caller's rung: `--pane-fill`
+ * in the app's frame, `sheet(1)`/`sheet(2)` where a pane lies in a room.
+ *
+ * The drop is a prop and not `sheet(2)`'s `elevation-2` class, whose shadow is
+ * `!important`: a Dev run's pane steps aside for the two panes inside it by
+ * slot (@hanzo/build's `run-split`), and an important shadow would stay behind.
+ */
+export const pane = (fill = 'var(--pane-fill)') => ({
+    backgroundColor: fill,
+    borderRadius: 'var(--pane-round)',
+    borderWidth: 1,
+    borderColor: 'var(--pane-edge)',
+    backdropFilter: 'var(--pane-blur)',
+    boxShadow: 'var(--shadow-sheet-2)',
+});
+/**
+ * THE FLOOR under the app's frame (app/_web.tsx, components/settings/Frame.tsx):
+ * design's top light falling off down the window over the faint lamps of
+ * `--pane-ground`. A straight fall rather than a radial glow, because at these
+ * alphas a circle quantises into rings a blur makes plainer.
+ */
+export const floor = {
+    backgroundColor: 'var(--pane-floor)',
+    backgroundImage: 'linear-gradient(to bottom, var(--glass-strong), transparent), var(--pane-ground)',
+    backgroundSize: '100% 70%, auto',
+    backgroundRepeat: 'no-repeat',
+};

package/dist/host.d.ts

@@ -0,0 +1,76 @@
+/**
+ * What a host tells the rooms.
+ *
+ * The rooms name no framework and no site. Everything that differs between the
+ * surfaces that mount them arrives here, in two halves, because two kinds of
+ * caller read them:
+ *
+ *   configure({ site: 'https://hanzo.ai', home: '/', signUp: '/start' })
+ *
+ *   <Rooms router={useRouter()} search={useSearchParams()} route={route} Link={Link}>
+ *     <Room mode="cal" />
+ *   </Rooms>
+ *
+ * The ADDRESSES — where the app's pages live, which gateway and IAM to talk to,
+ * the plan catalogue to paint first — do not change while the page is open, and
+ * plain modules (`api()`, `iam()`, `site()`, the plan reads) call them outside
+ * any component and on pages the rooms never draw. So the host states them once
+ * with `configure()`, in a module its root imports, before anything renders.
+ *
+ * The ROUTER, the query and the route change as the page moves, so they ride
+ * React context, and a room reads them with `useRooms()`.
+ */
+import { type AnchorHTMLAttributes, type ComponentType, type ReactNode } from 'react';
+/** A link the host's router owns: next/link under Next, an anchor elsewhere. */
+export type Link = ComponentType<AnchorHTMLAttributes<HTMLAnchorElement> & {
+    href: string;
+    prefetch?: boolean;
+}>;
+export interface Router {
+    push(href: string): void;
+    replace(href: string): void;
+    back(): void;
+    forward(): void;
+}
+interface Moving {
+    router: Router;
+    /** The address's query, for the rooms that read one (Dev's `?at=`). */
+    search: URLSearchParams | null;
+    route: string;
+    Link: Link;
+}
+export interface RoomsProps extends Omit<Moving, 'search'> {
+    /** Absent where no mounted room reads the query, so a static export needs no Suspense for it. */
+    search?: URLSearchParams | null;
+    children?: ReactNode;
+}
+/** The router, the query, the route and the link the host mounted the rooms with. */
+export declare const useRooms: () => Moving;
+/** The org in scope, by the id the appearance layers are keyed on. */
+export declare function useOrg(): {
+    id?: string;
+    name?: string;
+};
+/**
+ * The person's appearance — theme, type, spacing, corners, accent — resolved
+ * for the org in scope and kept with their IAM account, so a choice made here
+ * follows them to every Hanzo origin. Every control that changes how the rooms
+ * look goes through this, and only this.
+ */
+export declare function useLook(): {
+    pref: import("@hanzo/appearance").Preference;
+    set: (patch: Partial<import("@hanzo/appearance").Preference>) => void;
+    reset: () => void;
+    scope: import("@hanzo/appearance").Scope;
+    setScope: (s: import("@hanzo/appearance").Scope) => import("@hanzo/appearance").Resolved;
+    from: Partial<Record<keyof import("@hanzo/appearance").Preference, "install" | "org" | "user" | "userOrg">>;
+    layer: "user" | "userOrg";
+};
+/**
+ * The look, applied: mounted once at the host's root, inside its IamProvider,
+ * so every page — a room or not — opens in the person's theme and accent and
+ * keeps their choice in step with IAM.
+ */
+export declare function Look(): any;
+export declare function Rooms({ router, search, route, Link, children }: RoomsProps): import("react").JSX.Element;
+export {};

package/dist/host.js

@@ -0,0 +1,76 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * What a host tells the rooms.
+ *
+ * The rooms name no framework and no site. Everything that differs between the
+ * surfaces that mount them arrives here, in two halves, because two kinds of
+ * caller read them:
+ *
+ *   configure({ site: 'https://hanzo.ai', home: '/', signUp: '/start' })
+ *
+ *   <Rooms router={useRouter()} search={useSearchParams()} route={route} Link={Link}>
+ *     <Room mode="cal" />
+ *   </Rooms>
+ *
+ * The ADDRESSES — where the app's pages live, which gateway and IAM to talk to,
+ * the plan catalogue to paint first — do not change while the page is open, and
+ * plain modules (`api()`, `iam()`, `site()`, the plan reads) call them outside
+ * any component and on pages the rooms never draw. So the host states them once
+ * with `configure()`, in a module its root imports, before anything renders.
+ *
+ * The ROUTER, the query and the route change as the page moves, so they ride
+ * React context, and a room reads them with `useRooms()`.
+ */
+import { createContext, useContext } from 'react';
+import { useIam, useOrganizations } from '@hanzo/iam/react';
+import { useAppearance } from '@hanzo/appearance';
+import { where } from './where.js';
+const Plain = ({ prefetch: _prefetch, ...rest }) => _jsx("a", { ...rest });
+const Context = createContext({
+    router: {
+        push: (href) => window.location.assign(href),
+        replace: (href) => window.location.replace(href),
+        back: () => window.history.back(),
+        forward: () => window.history.forward(),
+    },
+    search: null,
+    route: '/',
+    Link: Plain,
+});
+/** The router, the query, the route and the link the host mounted the rooms with. */
+export const useRooms = () => useContext(Context);
+/** The org in scope, by the id the appearance layers are keyed on. */
+export function useOrg() {
+    const { currentOrg } = useOrganizations();
+    const one = currentOrg;
+    return { id: one?.id || one?.name, name: one?.displayName || one?.name };
+}
+/**
+ * The person's appearance — theme, type, spacing, corners, accent — resolved
+ * for the org in scope and kept with their IAM account, so a choice made here
+ * follows them to every Hanzo origin. Every control that changes how the rooms
+ * look goes through this, and only this.
+ */
+export function useLook() {
+    const { accessToken } = useIam();
+    const org = useOrg();
+    // Signed out there is no person to ask about, so IAM is not asked: a stranger
+    // passing through a room on the way to sign in sends nothing to the issuer.
+    return useAppearance({
+        org: org.id,
+        account: accessToken ? { base: (where().iam ?? 'https://hanzo.id').replace(/\/+$/, ''), token: accessToken } : undefined,
+    });
+}
+/**
+ * The look, applied: mounted once at the host's root, inside its IamProvider,
+ * so every page — a room or not — opens in the person's theme and accent and
+ * keeps their choice in step with IAM.
+ */
+export function Look() {
+    useLook();
+    return null;
+}
+export function Rooms({ router, search = null, route, Link, children }) {
+    return _jsx(Context.Provider, { value: { router, search, route, Link }, children: children });
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @hanzo/rooms — the workspace rooms, once, for every Hanzo surface.
+ *
+ *   import { configure, Rooms } from '@hanzo/rooms'
+ *   import { Room } from '@hanzo/rooms/Room'
+ *   import { CalScheduler } from '@hanzo/rooms/CalScheduler'
+ *
+ * The root names what a host passes; each room is its own subpath, so a page
+ * loads the rooms it draws and no others.
+ */
+export { configure, where, site } from './where.js';
+export type { Addresses } from './where.js';
+export { Rooms, Look, useRooms, useLook, useOrg } from './host.js';
+export type { Router, Link, RoomsProps } from './host.js';

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * @hanzo/rooms — the workspace rooms, once, for every Hanzo surface.
+ *
+ *   import { configure, Rooms } from '@hanzo/rooms'
+ *   import { Room } from '@hanzo/rooms/Room'
+ *   import { CalScheduler } from '@hanzo/rooms/CalScheduler'
+ *
+ * The root names what a host passes; each room is its own subpath, so a page
+ * loads the rooms it draws and no others.
+ */
+export { configure, where, site } from './where.js';
+export { Rooms, Look, useRooms, useLook, useOrg } from './host.js';

package/dist/kept.d.ts

@@ -0,0 +1,5 @@
+/**
+ * A value kept in this browser as JSON; storage that throws keeps it in memory.
+ * Read in the initializer: the app renders only in the browser (app/_apex.tsx).
+ */
+export declare function useKept<T>(key: string, initial: T): [T, (v: T) => void];

package/dist/kept.js

@@ -0,0 +1,27 @@
+'use client';
+import { useState } from 'react';
+/**
+ * A value kept in this browser as JSON; storage that throws keeps it in memory.
+ * Read in the initializer: the app renders only in the browser (app/_apex.tsx).
+ */
+export function useKept(key, initial) {
+    const [value, setValue] = useState(() => {
+        try {
+            const raw = localStorage.getItem(key);
+            return raw === null ? initial : JSON.parse(raw);
+        }
+        catch {
+            return initial;
+        }
+    });
+    const set = (v) => {
+        setValue(v);
+        try {
+            localStorage.setItem(key, JSON.stringify(v));
+        }
+        catch {
+            /* kept for this page only */
+        }
+    };
+    return [value, set];
+}

package/dist/lib/account.d.ts

@@ -0,0 +1,49 @@
+import React, { ReactNode } from 'react';
+export interface OrganizationMember {
+    id: string;
+    name: string;
+    email: string;
+    role: string;
+    avatar?: string;
+}
+export interface Organization {
+    id: string;
+    name: string;
+    /** The reader's role in it as the token's `orgs` claim states it: owner | admin | member. */
+    role: string;
+    avatar?: string;
+    plan?: string;
+    memberCount?: number;
+    members?: OrganizationMember[];
+    description?: string;
+    website?: string;
+    location?: string;
+}
+export interface User {
+    id: string;
+    name: string;
+    email: string;
+    avatar?: string;
+    bio?: string;
+    location?: string;
+    joinedDate?: string;
+    website?: string;
+    phone?: string;
+}
+interface AccountContextType {
+    user: User | null;
+    setUser: (user: User) => void;
+    organizations: Organization[];
+    currentOrganization: Organization | null;
+    isLoading: boolean;
+    switchOrganization: (orgId: string) => void;
+    /** Writes to IAM and resolves once the row is stored. Rejects with the
+     *  reason where it is not — a caller that reports success does so on this. */
+    updateUserProfile: (userData: Partial<User>) => Promise<void>;
+    updateOrganization: (orgData: Partial<Organization>) => void;
+}
+export declare const AccountProvider: React.FC<{
+    children: ReactNode;
+}>;
+export declare const useAccount: () => AccountContextType;
+export {};