@vibesdotdev/kit 0.0.0-stage → 1.0.0-rc.4

package/dist/lib/components/app-shell/schemas/app-navigation.d.ts

@@ -0,0 +1,170 @@
+import type { Component, Snippet } from 'svelte';
+/**
+ * Brand identity override for an app's chrome. When present, AppShell renders
+ * the tenant's logo and wordmark in place of the vibes.dev defaults. Used for
+ * white-labelled tenant apps (e.g. casework → Northwind) so the surface
+ * presents as a standalone product to its users.
+ */
+export interface VibesAppBrand {
+    /** Display name rendered in the sidebar header in place of "vibes.dev". */
+    name: string;
+    /** Product home, including packaged/file-backed destinations when applicable. */
+    homeHref?: string;
+    /**
+     * Logo override. Accepts an Iconify icon name (e.g. "lucide:briefcase"),
+     * a Svelte component, or a path/URL string (starts with "/" or "http").
+     */
+    logo?: string | Component;
+    /**
+     * Logo aspect hint for image URLs. 'square' (default) renders into a
+     * 40x40 box. 'wide' renders height-locked with auto width so a
+     * horizontal wordmark (e.g. Northwind Studio) displays uncropped.
+     */
+    logoAspect?: 'square' | 'wide';
+    /** Optional class applied to image logos for theme-specific contrast fixes. */
+    logoClass?: string;
+    /**
+     * Compact label rendered when a wide logo has no small mark and the
+     * sidebar collapses to icon-only mode. Defaults to the first character of
+     * the brand name.
+     */
+    compactLabel?: string;
+    /** Tailwind class applied to the compact initial mark. */
+    compactClass?: string;
+    /** Tailwind class applied to the wordmark text. */
+    wordmarkClass?: string;
+    /**
+     * Suppress the wordmark text next to the logo. Use when the logo image
+     * already embeds the brand name (typical for horizontal wordmarks).
+     */
+    hideWordmark?: boolean;
+    /**
+     * When true, the suite-wide app switcher is suppressed so the app reads as
+     * a standalone product. The user menu remains for sign-out / account
+     * access. Use for fully-branded tenant apps.
+     */
+    hideSuiteIdentity?: boolean;
+    /** Optional background color or gradient for circular mark badges. */
+    circleBg?: string;
+    /** Optional text / foreground color for circular mark badges. */
+    circleFg?: string;
+    /** Optional 1-4 character letter mark (e.g. "N" for Northwind). */
+    markLetter?: string;
+    /** Mark display style: logo image, letter mark badge, or icon. */
+    markType?: 'logo' | 'letter' | 'icon';
+}
+/**
+ * Visibility predicate for an app in the suite-wide app switcher.
+ *
+ *  - `public` (or omitted): visible to every signed-in suite user.
+ *  - `staff`: visible only to viewers with a staff/superuser flag, an admin
+ *    role, or a `system:read`/`*:*` permission. Matches the existing
+ *    canAccessSystem check used by app-web.
+ *  - `organization`: visible only to viewers with membership in at least one of the
+ *    listed org slugs.
+ */
+export type VibesAppAudience = {
+    kind: 'public';
+} | {
+    kind: 'staff';
+} | {
+    kind: 'organization';
+    organizationSlugs: readonly string[];
+};
+/**
+ * The data product hosts use to evaluate audience predicates. A subset of the
+ * data the layout already loads — kept loose so each app can pass through
+ * whatever ClientUser/AccountOrganizationContext shape it already has.
+ */
+export interface AppShellViewer {
+    user?: {
+        isSuperuser?: boolean | null;
+        isSuperUser?: boolean | null;
+        staff?: boolean | null;
+        isStaff?: boolean | null;
+        roles?: ReadonlyArray<{
+            name: string;
+        }> | null;
+        permissions?: readonly string[] | null;
+    } | null;
+    organizations?: ReadonlyArray<{
+        slug?: string | null;
+    }> | null;
+}
+export interface VibesAppLink {
+    id: string;
+    label: string;
+    description: string;
+    href: string;
+    /** Iconify icon name or a Svelte icon component. */
+    icon?: string | Component;
+    iconClass?: string;
+    external?: boolean;
+    /** When set, AppShell renders this app's chrome with a tenant brand. */
+    brand?: VibesAppBrand;
+    /** Visibility predicate for the suite-wide app switcher. */
+    audience?: VibesAppAudience;
+}
+export interface VibesAppGroup {
+    title: string;
+    items: VibesAppLink[];
+}
+export interface AppShellUser {
+    /** Stable user id — used by surfaces that scope to the viewer (e.g. the messenger). */
+    id?: string | null;
+    name?: string | null;
+    email?: string | null;
+    image?: string | null;
+}
+export type AppSidebarMatch = 'exact' | 'startsWith';
+export interface AppSidebarItem {
+    id?: string;
+    value?: string;
+    label: string;
+    href: string;
+    /** Iconify icon name or a Svelte icon component. */
+    icon?: string | Component;
+    iconClass?: string;
+    badge?: Snippet;
+    description?: string;
+    isActive?: boolean;
+    match?: AppSidebarMatch;
+    external?: boolean;
+    /**
+     * Force a full document navigation instead of SvelteKit client routing.
+     * Native static bundles use this when each route is emitted as its own
+     * document and cannot be resolved by the current page's client router.
+     */
+    reload?: boolean;
+    /**
+     * Nested child links (one level). When present, the sidebar renders this
+     * item as an expandable parent: an inline collapsible sub-menu when the
+     * sidebar is expanded, and a hover/focus pop-out flyout when collapsed to
+     * icon mode. Items without children render unchanged as flat leaf links.
+     */
+    children?: AppSidebarItem[];
+}
+export interface AppSidebarGroup {
+    id?: string;
+    /** Section header. Omit (with `collapsible: false`) for a header-less group —
+     *  a single flat item should not wear a group hat (e.g. a lone Settings link). */
+    title?: string;
+    items: AppSidebarItem[];
+    /** Iconify icon name or a Svelte icon component. */
+    icon?: string | Component;
+    iconClass?: string;
+    collapsible?: boolean;
+    defaultExpanded?: boolean;
+}
+/** Host-owned navigation. Kit renders these values without a product catalog. */
+export interface AppShellNavigationProjection {
+    currentAppId: string;
+    app?: VibesAppLink;
+    apps: VibesAppLink[];
+    groups: AppSidebarGroup[];
+    orgHomeApp?: VibesAppLink;
+    accountHref?: string;
+    workspaceHref?: string;
+    chatHref?: string;
+}
+export type VibesAppOriginMap = Readonly<Record<string, string | undefined>>;

package/dist/lib/components/app-shell/schemas/app-navigation.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/components/app-shell/schemas/app-shell-utility.d.ts

@@ -0,0 +1,124 @@
+/**
+ * `app-shell/utility`: a shell affordance (a report-a-problem button, a help
+ * panel) that any package contributes to every app through the runtime the
+ * shell is handed. Kit renders the trigger from the descriptor; the owner's
+ * loader supplies the component Kit mounts when the trigger is activated.
+ */
+import type { Component } from 'svelte';
+import * as z from 'zod/v4';
+export declare const APP_SHELL_UTILITY_KIND: "app-shell/utility";
+/** Runtime-scoped open requests (`openAppShellUtility`) travel through this context. */
+export declare const APP_SHELL_UTILITY_HOST_CONTEXT_ID: "app-shell/utility-host";
+/** The plugin that registers the kind; contributing plugins list it in `dependencies`. */
+export declare const APP_SHELL_PLUGIN_ID: "@vibesdotdev/kit/app-shell";
+export declare const AppShellUtilityPlacementSchema: z.ZodEnum<{
+    header: "header";
+    "user-menu": "user-menu";
+}>;
+/**
+ * Who sees a utility, and where:
+ * - `always`: every viewer, in the shell and on Kit's error surface.
+ * - `signed-in`: signed-in viewers only, in the shell and on the error surface.
+ * - `on-error`: signed-in viewers always; signed-out visitors only on Kit's
+ *   error surface (`ErrorPage`).
+ */
+export declare const AppShellUtilityVisibilitySchema: z.ZodEnum<{
+    always: "always";
+    "signed-in": "signed-in";
+    "on-error": "on-error";
+}>;
+/**
+ * Strict on top of the kernel's descriptor fields, so a misspelled field
+ * refuses at registration instead of silently rendering a default.
+ */
+export declare const AppShellUtilityDescriptorSchema: z.ZodObject<{
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    hardware: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    priority: z.ZodOptional<z.ZodNumber>;
+    capabilityId: z.ZodOptional<z.ZodString>;
+    requiredContext: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    optionalContext: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    config: z.ZodOptional<z.ZodUnknown>;
+    retention: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        maxAgeDays: z.ZodOptional<z.ZodNumber>;
+        maxEntries: z.ZodOptional<z.ZodNumber>;
+        maxBytes: z.ZodOptional<z.ZodNumber>;
+        cascadeFrom: z.ZodOptional<z.ZodString>;
+        ageField: z.ZodOptional<z.ZodString>;
+        reason: z.ZodString;
+        enforcedBy: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>>;
+    kind: z.ZodLiteral<"app-shell/utility">;
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    icon: z.ZodString;
+    placement: z.ZodEnum<{
+        header: "header";
+        "user-menu": "user-menu";
+    }>;
+    order: z.ZodDefault<z.ZodNumber>;
+    visibility: z.ZodEnum<{
+        always: "always";
+        "signed-in": "signed-in";
+        "on-error": "on-error";
+    }>;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>;
+export type AppShellUtilityPlacement = z.infer<typeof AppShellUtilityPlacementSchema>;
+export type AppShellUtilityVisibility = z.infer<typeof AppShellUtilityVisibilitySchema>;
+export type AppShellUtilityDescriptor = z.output<typeof AppShellUtilityDescriptorSchema>;
+export type AppShellUtilityDescriptorInput = z.input<typeof AppShellUtilityDescriptorSchema>;
+/** Parse a utility descriptor at its declaration site. */
+export declare function defineAppShellUtility(descriptor: Omit<AppShellUtilityDescriptorInput, 'kind'> & {
+    kind?: typeof APP_SHELL_UTILITY_KIND;
+}): AppShellUtilityDescriptor;
+/** Where Kit is rendering: the product shell chrome, or its error surface. */
+export type AppShellUtilitySurface = 'shell' | 'error';
+export interface AppShellUtilityViewer {
+    signedIn: boolean;
+    surface: AppShellUtilitySurface;
+}
+/** The single visibility rule every Kit surface applies. */
+export declare function isAppShellUtilityVisible(utility: Pick<AppShellUtilityDescriptor, 'visibility' | 'enabled'>, viewer: AppShellUtilityViewer): boolean;
+/** Order utilities for display: `order` ascending, then id. */
+export declare function sortAppShellUtilities<T extends Pick<AppShellUtilityDescriptor, 'order' | 'id'>>(utilities: readonly T[]): T[];
+/** The error a Kit error surface is showing; never carries a stack or request. */
+export interface AppShellUtilityError {
+    status: number;
+    message?: string;
+}
+/** Props Kit hands every utility component it mounts. Closed: no host objects. */
+export interface AppShellUtilityProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    utility: AppShellUtilityDescriptor;
+    surface: AppShellUtilitySurface;
+    /** The trigger that opened it: a shell placement, or the error surface. */
+    placement: AppShellUtilityPlacement | 'error';
+    signedIn: boolean;
+    error?: AppShellUtilityError;
+    /**
+     * The host's route template (SvelteKit `page.route.id`, e.g.
+     * `/projects/[id]`), never a concrete path. Absent when the host did not
+     * supply one.
+     */
+    route?: string;
+}
+/** What an `app-shell/utility` loader resolves to. */
+export type AppShellUtilityComponent = Component<AppShellUtilityProps>;
+/**
+ * A mounted Kit surface that can open utilities. `open` answers whether this
+ * surface currently shows `id` to its viewer and opened it.
+ */
+export interface AppShellUtilitySurfaceHandle {
+    open(id: string): boolean;
+}
+/** Runtime-scoped open requests: one per runtime, provided by the app-shell plugin. */
+export interface AppShellUtilityHost {
+    /** Attach a mounted surface; the returned function detaches it. */
+    attach(surface: AppShellUtilitySurfaceHandle): () => void;
+    /** Offer the request to attached surfaces, most recently attached first. */
+    open(id: string): boolean;
+}
+export declare const AppShellUtilityIdSchema: z.ZodString;

package/dist/lib/components/app-shell/schemas/app-shell-utility.js

@@ -0,0 +1,61 @@
+import * as z from 'zod/v4';
+import { RuntimeDescriptorSchema } from '@vibesdotdev/kernel/schemas/descriptor';
+export const APP_SHELL_UTILITY_KIND = 'app-shell/utility';
+/** Runtime-scoped open requests (`openAppShellUtility`) travel through this context. */
+export const APP_SHELL_UTILITY_HOST_CONTEXT_ID = 'app-shell/utility-host';
+/** The plugin that registers the kind; contributing plugins list it in `dependencies`. */
+export const APP_SHELL_PLUGIN_ID = '@vibesdotdev/kit/app-shell';
+export const AppShellUtilityPlacementSchema = z.enum(['header', 'user-menu']);
+/**
+ * Who sees a utility, and where:
+ * - `always`: every viewer, in the shell and on Kit's error surface.
+ * - `signed-in`: signed-in viewers only, in the shell and on the error surface.
+ * - `on-error`: signed-in viewers always; signed-out visitors only on Kit's
+ *   error surface (`ErrorPage`).
+ */
+export const AppShellUtilityVisibilitySchema = z.enum(['always', 'signed-in', 'on-error']);
+const UtilityIdSchema = z
+    .string()
+    .min(1)
+    .max(128)
+    .regex(/^[a-z0-9][a-z0-9._/-]*$/, 'lowercase id of letters, digits, ".", "_", "/" or "-"');
+/**
+ * Strict on top of the kernel's descriptor fields, so a misspelled field
+ * refuses at registration instead of silently rendering a default.
+ */
+export const AppShellUtilityDescriptorSchema = RuntimeDescriptorSchema.extend({
+    kind: z.literal(APP_SHELL_UTILITY_KIND),
+    id: UtilityIdSchema,
+    /** Trigger label and accessible name. */
+    name: z.string().min(1).max(80),
+    description: z.string().max(280).optional(),
+    /** Iconify name rendered on the trigger, e.g. `lucide:bug`. */
+    icon: z.string().min(1).max(80),
+    placement: AppShellUtilityPlacementSchema,
+    /** Ascending within a placement; ties order by id. */
+    order: z.number().int().default(0),
+    visibility: AppShellUtilityVisibilitySchema,
+    enabled: z.boolean().default(true)
+}).strict();
+/** Parse a utility descriptor at its declaration site. */
+export function defineAppShellUtility(descriptor) {
+    return AppShellUtilityDescriptorSchema.parse({ ...descriptor, kind: APP_SHELL_UTILITY_KIND });
+}
+/** The single visibility rule every Kit surface applies. */
+export function isAppShellUtilityVisible(utility, viewer) {
+    if (!utility.enabled)
+        return false;
+    switch (utility.visibility) {
+        case 'always':
+            return true;
+        case 'signed-in':
+            return viewer.signedIn;
+        case 'on-error':
+            return viewer.signedIn || viewer.surface === 'error';
+    }
+}
+/** Order utilities for display: `order` ascending, then id. */
+export function sortAppShellUtilities(utilities) {
+    return [...utilities].sort((left, right) => left.order - right.order || left.id.localeCompare(right.id));
+}
+export const AppShellUtilityIdSchema = UtilityIdSchema;

package/dist/lib/components/app-shell/shell-location.d.ts

@@ -0,0 +1,13 @@
+export interface AppShellLocation {
+    readonly origin?: string;
+    readonly pathname: string;
+    readonly search?: string;
+    readonly hash?: string;
+}
+export interface ResolvedAppShellLocation {
+    readonly origin: string;
+    readonly pathname: string;
+    readonly search: string;
+    readonly hash: string;
+}
+export declare function resolveAppShellLocation(location: AppShellLocation | undefined, fallbackPathname?: string): ResolvedAppShellLocation;

package/dist/lib/components/app-shell/shell-location.js

@@ -0,0 +1,16 @@
+/**
+ * Transport-blind location input for reusable shell components.
+ *
+ * SvelteKit consumers can pass `page.url` directly. Other hosts may pass a
+ * plain object or omit it and let a browser-hosted shell read `window.location`.
+ */
+import { BROWSER } from 'esm-env';
+export function resolveAppShellLocation(location, fallbackPathname = '') {
+    const browserLocation = BROWSER ? window.location : undefined;
+    return {
+        origin: location?.origin ?? browserLocation?.origin ?? '',
+        pathname: location?.pathname || fallbackPathname || browserLocation?.pathname || '/',
+        search: location?.search ?? browserLocation?.search ?? '',
+        hash: location?.hash ?? browserLocation?.hash ?? ''
+    };
+}

package/dist/lib/components/app-shell/shell-style-store.svelte.d.ts

@@ -0,0 +1,16 @@
+import type { ShellStyle } from './shell-style';
+import type { PreferenceStorage } from '../../preferences/preference-storage.ts';
+export declare class ShellStyleStore {
+    #private;
+    constructor();
+    /** The user's explicit preference, if any. Undefined = follow app default. */
+    get preference(): ShellStyle | undefined;
+    /**
+     * Bind the runtime's preference storage (a shell resolves it from its
+     * runtime). Adopts a stored choice when no cookie or override set one, then
+     * mirrors the current choice into storage.
+     */
+    attachStorage(storage: PreferenceStorage): void;
+    set(style: ShellStyle): void;
+}
+export type { ShellStyle };

package/dist/lib/components/app-shell/shell-style-store.svelte.js

@@ -0,0 +1,59 @@
+/**
+ * Client-side shell-style preference store. Initializes from the URL override
+ * / cookie on first client read (and the runtime preference storage once a
+ * shell attaches it) (SSR returns undefined so the
+ * server render uses the app-provided `chrome` default; apps that read the
+ * cookie server-side and pass `chrome` get a flash-free first paint).
+ */
+import { BROWSER } from 'esm-env';
+import * as z from 'zod/v4';
+import { SHELL_STYLES, coerceShellStyle, persistShellStylePreference, readClientShellStyle } from './shell-style';
+import { failureClass } from "../../failure-class.js";
+import { kitLogger } from '../../kit-logger';
+const ShellStyleEventDetail = z.enum(SHELL_STYLES);
+const logger = kitLogger('vibeskit-app-shell-shell-style-store');
+export class ShellStyleStore {
+    /*
+     * Initialized eagerly at construction (module import), never inside the
+     * getter — components read `preference` from $derived scopes, and lazy
+     * initialization there is a state_unsafe_mutation. On the server the
+     * module constructs with undefined, so SSR renders the app default.
+     */
+    #preference = $state(BROWSER ? readClientShellStyle() : undefined);
+    #storage;
+    constructor() {
+        if (BROWSER) {
+            window.addEventListener('vibes:shell-style-changed', (e) => {
+                const style = ShellStyleEventDetail.safeParse(e instanceof CustomEvent ? e.detail : undefined);
+                if (style.success) {
+                    this.set(style.data);
+                }
+            });
+        }
+    }
+    /** The user's explicit preference, if any. Undefined = follow app default. */
+    get preference() {
+        return this.#preference;
+    }
+    /**
+     * Bind the runtime's preference storage (a shell resolves it from its
+     * runtime). Adopts a stored choice when no cookie or override set one, then
+     * mirrors the current choice into storage.
+     */
+    attachStorage(storage) {
+        this.#storage = storage;
+        const adopted = this.#preference ?? readClientShellStyle(storage);
+        if (adopted)
+            this.set(adopted);
+    }
+    set(style) {
+        const coerced = coerceShellStyle(style);
+        if (!coerced)
+            return;
+        this.#preference = coerced;
+        const persisted = persistShellStylePreference(coerced, this.#storage);
+        if (!persisted.ok) {
+            logger.warn('Shell style storage mirror refused', { reason: failureClass(persisted.error) });
+        }
+    }
+}

package/dist/lib/components/app-shell/shell-style.d.ts

@@ -0,0 +1,44 @@
+import { type Settled } from '../../attempt.ts';
+import type { PreferenceStorage } from '../../preferences/preference-storage.ts';
+export declare const SHELL_STYLES: readonly ["suite", "focus", "canvas"];
+export type ShellStyle = (typeof SHELL_STYLES)[number];
+export declare const SHELL_STYLE_COOKIE_NAME = "vibes-shell-style";
+export declare const SHELL_STYLE_STORAGE_KEY = "vibes-shell-style";
+export declare const SHELL_STYLE_MAX_AGE: number;
+/** URL override for reviews/demos: ?chrome=focus persists then cleans itself. */
+export declare const SHELL_STYLE_QUERY_PARAM = "chrome";
+export type ShellStyleMeta = {
+    label: string;
+    description: string;
+    icon: string;
+};
+export declare const SHELL_STYLE_META: {
+    suite: {
+        label: string;
+        description: string;
+        icon: string;
+    };
+    focus: {
+        label: string;
+        description: string;
+        icon: string;
+    };
+    canvas: {
+        label: string;
+        description: string;
+        icon: string;
+    };
+};
+export declare function coerceShellStyle(value: string | null | undefined): ShellStyle | undefined;
+/** Parse the preference out of a Cookie header / document.cookie string. */
+export declare function readShellStyleCookie(cookieString: string | undefined): ShellStyle | undefined;
+/**
+ * Persist the preference cookie (cross-subdomain) + the runtime storage
+ * mirror. The cookie is authoritative; without `storage` (no runtime browser
+ * host) only the cookie is written. The mirror's outcome (refused in private
+ * mode) is returned.
+ */
+export declare function persistShellStylePreference(style: ShellStyle, storage?: PreferenceStorage): Settled<void>;
+/** Client read: URL override, server-resolved appearance, then cookie, then the runtime storage mirror. */
+export declare function readClientShellStyle(storage?: PreferenceStorage): ShellStyle | undefined;
+export declare function resolveShellStyle(preference: ShellStyle | undefined, appDefault: ShellStyle | undefined): ShellStyle;

package/dist/lib/components/app-shell/shell-style.js

@@ -0,0 +1,108 @@
+/**
+ * Shell style ("Suite" / "Focus" / "Canvas") — the user-selectable chrome
+ * anatomy for ProductShell (docs/proposals/appshell-apple-design/PROPOSAL.md,
+ * approved 2026-07-26).
+ *
+ * Persistence mirrors the shared mode system (shared-mode-sync.ts): one
+ * cross-subdomain cookie so the choice follows the user across the suite, plus
+ * a mirror in the runtime's preference storage (`runtime/browser-host`) for
+ * fast client reads. Apps that want a flash-free
+ * SSR render read the cookie server-side and pass `chrome` to the shell
+ * (see AppShell/VibesAppShell pass-through).
+ *
+ * Resolution order (resolveShellStyle): user preference → app default →
+ * 'suite'. Org descriptors can pin an anatomy by passing `chrome` +
+ * `chromeLocked` from their layout; a locked shell ignores the cookie and
+ * hides the picker.
+ */
+import { BROWSER } from 'esm-env';
+import { settleNow } from "../../attempt.js";
+import { failureClass } from "../../failure-class.js";
+import { kitLogger } from "../../kit-logger.js";
+import { deriveSharedCookieDomain } from "../ui/mode-switcher/shared-mode-sync.js";
+const logger = kitLogger('vibeskit-app-shell-shell-style');
+export const SHELL_STYLES = ['suite', 'focus', 'canvas'];
+export const SHELL_STYLE_COOKIE_NAME = 'vibes-shell-style';
+export const SHELL_STYLE_STORAGE_KEY = 'vibes-shell-style';
+export const SHELL_STYLE_MAX_AGE = 60 * 60 * 24 * 365;
+/** URL override for reviews/demos: ?chrome=focus persists then cleans itself. */
+export const SHELL_STYLE_QUERY_PARAM = 'chrome';
+export const SHELL_STYLE_META = {
+    suite: {
+        label: 'Suite',
+        description: 'See every vibes app at a glance.',
+        icon: 'lucide:panels-left-bottom'
+    },
+    focus: {
+        label: 'Focus',
+        description: 'One app at a time, chrome out of the way.',
+        icon: 'lucide:panel-left'
+    },
+    canvas: {
+        label: 'Canvas',
+        description: 'Maximum room for your work.',
+        icon: 'lucide:rectangle-horizontal'
+    }
+};
+function isShellStyle(value) {
+    return SHELL_STYLES.some((style) => style === value);
+}
+export function coerceShellStyle(value) {
+    return value && isShellStyle(value) ? value : undefined;
+}
+/** Parse the preference out of a Cookie header / document.cookie string. */
+export function readShellStyleCookie(cookieString) {
+    if (!cookieString)
+        return undefined;
+    const match = cookieString
+        .split(';')
+        .map((part) => part.trim())
+        .find((part) => part.startsWith(`${SHELL_STYLE_COOKIE_NAME}=`));
+    return coerceShellStyle(match?.slice(SHELL_STYLE_COOKIE_NAME.length + 1));
+}
+/**
+ * Persist the preference cookie (cross-subdomain) + the runtime storage
+ * mirror. The cookie is authoritative; without `storage` (no runtime browser
+ * host) only the cookie is written. The mirror's outcome (refused in private
+ * mode) is returned.
+ */
+export function persistShellStylePreference(style, storage) {
+    if (!BROWSER)
+        return { ok: true, value: undefined };
+    const domain = deriveSharedCookieDomain(window.location.hostname);
+    const domainPart = domain ? `; Domain=${domain}` : '';
+    document.cookie = `${SHELL_STYLE_COOKIE_NAME}=${style}; Max-Age=${SHELL_STYLE_MAX_AGE}; Path=/${domainPart}; SameSite=Lax`;
+    if (!storage)
+        return { ok: true, value: undefined };
+    return settleNow(() => storage.setItem(SHELL_STYLE_STORAGE_KEY, style));
+}
+/** Client read: URL override, server-resolved appearance, then cookie, then the runtime storage mirror. */
+export function readClientShellStyle(storage) {
+    if (!BROWSER)
+        return undefined;
+    const fromQuery = coerceShellStyle(new URLSearchParams(window.location.search).get(SHELL_STYLE_QUERY_PARAM));
+    if (fromQuery) {
+        const persisted = persistShellStylePreference(fromQuery, storage);
+        if (!persisted.ok) {
+            logger.warn('Shell style storage mirror refused', { reason: failureClass(persisted.error) });
+        }
+        return fromQuery;
+    }
+    const fromServer = coerceShellStyle(document.documentElement.dataset.shellStyle);
+    if (fromServer)
+        return fromServer;
+    const fromCookie = readShellStyleCookie(document.cookie);
+    if (fromCookie)
+        return fromCookie;
+    if (!storage)
+        return undefined;
+    // Storage that refuses the read holds no preference.
+    const stored = settleNow(() => storage.getItem(SHELL_STYLE_STORAGE_KEY));
+    if (stored.ok)
+        return coerceShellStyle(stored.value);
+    logger.warn('Shell style storage read refused', { reason: failureClass(stored.error) });
+    return undefined;
+}
+export function resolveShellStyle(preference, appDefault) {
+    return preference ?? appDefault ?? 'suite';
+}