@openchamber/sdk 2.1.0 → 2.2.0

package/dist/status-control-schemas.d.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+export declare const guestStatusControlsSchema: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"button">;
+    id: z.ZodString;
+    label: z.ZodString;
+    disabled: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"select">;
+    id: z.ZodString;
+    label: z.ZodString;
+    value: z.ZodString;
+    options: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strict>>;
+    disabled: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>], "kind">>;
+export declare const guestStatusControlEventSchema: z.ZodObject<{
+    id: z.ZodString;
+    value: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;

package/dist/status-control-schemas.js

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import { GUEST_STATUS_CONTROL_ID, GUEST_STATUS_CONTROL_LABEL_MAX, GUEST_STATUS_CONTROL_OPTIONS_MAX, GUEST_STATUS_CONTROL_VALUE_MAX, GUEST_STATUS_CONTROLS_MAX, } from "./status-controls.js";
+const idSchema = z.string().regex(GUEST_STATUS_CONTROL_ID);
+const labelSchema = z.string().min(1).max(GUEST_STATUS_CONTROL_LABEL_MAX);
+const optionSchema = z.object({
+    value: z.string().min(1).max(GUEST_STATUS_CONTROL_VALUE_MAX),
+    label: labelSchema,
+}).strict();
+const buttonSchema = z.object({
+    kind: z.literal('button'),
+    id: idSchema,
+    label: labelSchema,
+    disabled: z.boolean().optional(),
+}).strict();
+const selectSchema = z.object({
+    kind: z.literal('select'),
+    id: idSchema,
+    label: labelSchema,
+    value: z.string().min(1).max(GUEST_STATUS_CONTROL_VALUE_MAX),
+    options: z.array(optionSchema).min(1).max(GUEST_STATUS_CONTROL_OPTIONS_MAX),
+    disabled: z.boolean().optional(),
+}).strict().refine((control) => new Set(control.options.map((option) => option.value)).size === control.options.length, { message: 'status control option values must be unique', path: ['options'] }).refine((control) => control.options.some((option) => option.value === control.value), { message: 'status control value must be one of its options', path: ['value'] });
+export const guestStatusControlsSchema = z.array(z.discriminatedUnion('kind', [buttonSchema, selectSchema]))
+    .max(GUEST_STATUS_CONTROLS_MAX)
+    .refine((controls) => new Set(controls.map((control) => control.id)).size === controls.length, { message: 'status control ids must be unique' });
+export const guestStatusControlEventSchema = z.object({
+    id: idSchema,
+    value: z.string().min(1).max(GUEST_STATUS_CONTROL_VALUE_MAX).optional(),
+}).strict();

package/dist/status-controls.d.ts

@@ -0,0 +1,31 @@
+export declare const GUEST_STATUS_CONTROLS_MAX = 4;
+export declare const GUEST_STATUS_CONTROL_ID: RegExp;
+export declare const GUEST_STATUS_CONTROL_LABEL_MAX = 60;
+export declare const GUEST_STATUS_CONTROL_OPTIONS_MAX = 16;
+export declare const GUEST_STATUS_CONTROL_VALUE_MAX = 80;
+export type GuestStatusControlOption = {
+    value: string;
+    label: string;
+};
+export type GuestStatusControl = {
+    kind: 'button';
+    id: string;
+    label: string;
+    disabled?: boolean;
+} | {
+    kind: 'select';
+    id: string;
+    label: string;
+    value: string;
+    options: GuestStatusControlOption[];
+    disabled?: boolean;
+};
+export type GuestStatusControlEvent = {
+    id: string;
+    value?: string;
+};
+/**
+ * Guest-side fast-fail guard for `setStatusControls`. The host zod schema is
+ * still authoritative because JavaScript callers can bypass this SDK method.
+ */
+export declare const isGuestStatusControls: (controls: GuestStatusControl[]) => boolean;

package/dist/status-controls.js

@@ -0,0 +1,48 @@
+export const GUEST_STATUS_CONTROLS_MAX = 4;
+export const GUEST_STATUS_CONTROL_ID = /^[a-z][a-z0-9-]{0,39}$/;
+export const GUEST_STATUS_CONTROL_LABEL_MAX = 60;
+export const GUEST_STATUS_CONTROL_OPTIONS_MAX = 16;
+export const GUEST_STATUS_CONTROL_VALUE_MAX = 80;
+const isControlObject = (value) => (Object(value) === value && !Array.isArray(value));
+const hasOnlyKeys = (value, keys) => Object.keys(value).every((key) => keys.includes(key));
+const isLabel = (value) => (String(value) === value && value.length >= 1 && value.length <= GUEST_STATUS_CONTROL_LABEL_MAX);
+const isValue = (value) => (String(value) === value && value.length >= 1 && value.length <= GUEST_STATUS_CONTROL_VALUE_MAX);
+/**
+ * Guest-side fast-fail guard for `setStatusControls`. The host zod schema is
+ * still authoritative because JavaScript callers can bypass this SDK method.
+ */
+export const isGuestStatusControls = (controls) => {
+    // The public type is precise, but this boundary also receives untyped JavaScript callers.
+    if (!Array.isArray(controls) || controls.length > GUEST_STATUS_CONTROLS_MAX)
+        return false;
+    const ids = new Set();
+    for (const control of controls) {
+        if (!isControlObject(control) || !GUEST_STATUS_CONTROL_ID.test(control.id) || !isLabel(control.label))
+            return false;
+        if (control.disabled !== undefined && control.disabled !== true && control.disabled !== false)
+            return false;
+        if (ids.has(control.id))
+            return false;
+        ids.add(control.id);
+        if (control.kind === 'button') {
+            if (!hasOnlyKeys(control, ['kind', 'id', 'label', 'disabled']))
+                return false;
+            continue;
+        }
+        if (control.kind !== 'select' || !hasOnlyKeys(control, ['kind', 'id', 'label', 'value', 'options', 'disabled']))
+            return false;
+        if (!isValue(control.value) || !Array.isArray(control.options)
+            || control.options.length < 1 || control.options.length > GUEST_STATUS_CONTROL_OPTIONS_MAX)
+            return false;
+        const values = new Set();
+        for (const option of control.options) {
+            if (!isControlObject(option) || !hasOnlyKeys(option, ['value', 'label'])
+                || !isValue(option.value) || !isLabel(option.label) || values.has(option.value))
+                return false;
+            values.add(option.value);
+        }
+        if (!values.has(control.value))
+            return false;
+    }
+    return true;
+};

package/dist/ui/index.d.ts

@@ -33,3 +33,5 @@ export { mountMenu } from './menu.ts';
 export type { MenuHandle, MenuItem, MenuProps } from './menu.ts';
 export { mountText, splitTextMedia } from './text.ts';
 export type { TextHandle, TextPart, TextProps } from './text.ts';
+export { mountPopoverAnchor } from './popover-anchor.ts';
+export type { PopoverAnchorHandle, PopoverAnchorOptions } from './popover-anchor.ts';

package/dist/ui/index.js

@@ -15,3 +15,4 @@ export { mountSeparator } from "./separator.js";
 export { mountProgress } from "./progress.js";
 export { mountMenu } from "./menu.js";
 export { mountText, splitTextMedia } from "./text.js";
+export { mountPopoverAnchor } from "./popover-anchor.js";

package/dist/ui/popover-anchor.d.ts

@@ -0,0 +1,16 @@
+import type { HostClient } from '../host.ts';
+import type { GuestPopoverSide } from '../popover.ts';
+import type { JsonValue } from '../contract.ts';
+export type PopoverAnchorOptions = {
+    host: Pick<HostClient, 'openPopover' | 'closePopover' | 'setPopoverAnchorActive' | 'onPopoverClosed'>;
+    getData: () => JsonValue;
+    width: number;
+    height: number;
+    side?: GuestPopoverSide;
+    label?: string;
+};
+export type PopoverAnchorHandle = {
+    dispose: () => void;
+};
+/** Adds a bounded host popover preview to an extension-owned element. */
+export declare const mountPopoverAnchor: (element: HTMLElement, options: PopoverAnchorOptions) => PopoverAnchorHandle;

package/dist/ui/popover-anchor.js

@@ -0,0 +1,198 @@
+let nextPopoverAnchorId = 0;
+const isKeyboardEvent = (event) => 'key' in event;
+/** Adds a bounded host popover preview to an extension-owned element. */
+export const mountPopoverAnchor = (element, options) => {
+    const document = element.ownerDocument;
+    const window = document.defaultView;
+    let timer = null;
+    let activeId = null;
+    let disposed = false;
+    let ignoreNextFocus = false;
+    let pointerActive = false;
+    let focusActive = false;
+    let observer = null;
+    const previousExpanded = element.getAttribute('aria-expanded');
+    const previousPopup = element.getAttribute('aria-haspopup');
+    const previousLabel = element.getAttribute('aria-label');
+    const ownsExpanded = previousExpanded === null;
+    const clearTimer = () => {
+        if (timer !== null)
+            clearTimeout(timer);
+        timer = null;
+    };
+    const removeActiveListeners = () => {
+        document.removeEventListener('scroll', closeForAnchor, true);
+        document.removeEventListener('pointerdown', closeForOutside, true);
+        window?.removeEventListener('resize', closeForAnchor);
+        observer?.disconnect();
+        observer = null;
+    };
+    const close = (reason = 'closed', restoreFocus = false) => {
+        const id = activeId;
+        clearTimer();
+        activeId = null;
+        removeActiveListeners();
+        element.removeAttribute('data-oc-popover-open');
+        if (ownsExpanded)
+            element.setAttribute('aria-expanded', 'false');
+        if (id)
+            void options.host.closePopover(id, reason).catch(() => undefined);
+        if (restoreFocus) {
+            ignoreNextFocus = true;
+            element.focus();
+            queueMicrotask(() => { ignoreNextFocus = false; });
+        }
+    };
+    const closeForAnchor = () => close();
+    const closeForOutside = (event) => {
+        const target = event.target;
+        // SAFETY: DOM pointer events target a Node; this avoids cross-realm constructors.
+        if (target !== element && !element.contains(target))
+            close();
+    };
+    const watchActive = () => {
+        document.addEventListener('scroll', closeForAnchor, true);
+        document.addEventListener('pointerdown', closeForOutside, true);
+        window?.addEventListener('resize', closeForAnchor);
+        observer = new MutationObserver(() => { if (!document.contains(element))
+            close(); });
+        observer.observe(document, { childList: true, subtree: true });
+    };
+    const reportAnchorActivity = () => {
+        if (activeId)
+            void options.host.setPopoverAnchorActive(activeId, pointerActive || focusActive).catch(() => undefined);
+    };
+    const open = (focus) => {
+        clearTimer();
+        if (disposed || activeId || !element.isConnected)
+            return;
+        const rect = element.getBoundingClientRect();
+        if (rect.width <= 0 || rect.height <= 0)
+            return;
+        const id = `oc-popover-${++nextPopoverAnchorId}`;
+        let data;
+        try {
+            data = options.getData();
+        }
+        catch {
+            return;
+        }
+        activeId = id;
+        element.setAttribute('data-oc-popover-open', 'true');
+        if (ownsExpanded)
+            element.setAttribute('aria-expanded', 'true');
+        watchActive();
+        void options.host.openPopover({
+            id,
+            anchor: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
+            width: options.width,
+            height: options.height,
+            side: options.side,
+            focus,
+            data,
+        }).catch(() => {
+            if (activeId === id)
+                close();
+        });
+    };
+    const scheduleOpen = () => {
+        if (!activeId && !disposed && timer === null)
+            timer = setTimeout(() => open(false), 250);
+    };
+    const onPointerEnter = (event) => {
+        if ('pointerType' in event && event.pointerType && event.pointerType !== 'mouse')
+            return;
+        pointerActive = true;
+        if (activeId)
+            reportAnchorActivity();
+        else if (!ignoreNextFocus)
+            scheduleOpen();
+    };
+    const onPointerLeave = (event) => {
+        if ('pointerType' in event && event.pointerType && event.pointerType !== 'mouse')
+            return;
+        pointerActive = false;
+        clearTimer();
+        reportAnchorActivity();
+    };
+    const onFocus = () => {
+        focusActive = true;
+        if (activeId)
+            reportAnchorActivity();
+        else if (!ignoreNextFocus && element.matches(':focus-visible'))
+            open(false);
+    };
+    const onFocusOut = () => {
+        focusActive = false;
+        reportAnchorActivity();
+    };
+    const onKeyDown = (event) => {
+        if (!isKeyboardEvent(event))
+            return;
+        if (event.key === 'ArrowRight') {
+            event.preventDefault();
+            if (activeId)
+                close();
+            open(true);
+        }
+        else if (event.key === 'Escape' && activeId) {
+            event.preventDefault();
+            close('escape', true);
+        }
+    };
+    const unsubscribe = options.host.onPopoverClosed((event) => {
+        if (event.id !== activeId)
+            return;
+        activeId = null;
+        clearTimer();
+        removeActiveListeners();
+        element.removeAttribute('data-oc-popover-open');
+        if (ownsExpanded)
+            element.setAttribute('aria-expanded', 'false');
+        if (event.reason === 'escape') {
+            ignoreNextFocus = true;
+            element.focus();
+            queueMicrotask(() => { ignoreNextFocus = false; });
+        }
+    });
+    element.setAttribute('aria-haspopup', 'dialog');
+    if (ownsExpanded)
+        element.setAttribute('aria-expanded', 'false');
+    if (options.label)
+        element.setAttribute('aria-label', options.label);
+    element.addEventListener('pointerenter', onPointerEnter);
+    // Crossing opaque iframe documents can omit an enter transition. A real
+    // pointer move over this element still establishes a new hover intent.
+    element.addEventListener('pointermove', onPointerEnter);
+    element.addEventListener('pointerleave', onPointerLeave);
+    element.addEventListener('focus', onFocus);
+    element.addEventListener('focusout', onFocusOut);
+    element.addEventListener('keydown', onKeyDown);
+    return { dispose: () => {
+            if (disposed)
+                return;
+            disposed = true;
+            clearTimer();
+            close();
+            unsubscribe();
+            element.removeAttribute('data-oc-popover-open');
+            if (previousExpanded === null)
+                element.removeAttribute('aria-expanded');
+            if (previousPopup === null)
+                element.removeAttribute('aria-haspopup');
+            else
+                element.setAttribute('aria-haspopup', previousPopup);
+            if (options.label) {
+                if (previousLabel === null)
+                    element.removeAttribute('aria-label');
+                else
+                    element.setAttribute('aria-label', previousLabel);
+            }
+            element.removeEventListener('pointerenter', onPointerEnter);
+            element.removeEventListener('pointermove', onPointerEnter);
+            element.removeEventListener('pointerleave', onPointerLeave);
+            element.removeEventListener('focus', onFocus);
+            element.removeEventListener('focusout', onFocusOut);
+            element.removeEventListener('keydown', onKeyDown);
+        } };
+};

package/dist/ui/theme.js

@@ -54,6 +54,16 @@ const TOKEN_VARS = [
     ['--font-mono', 'mono'],
     ['--radius', 'radius'],
 ];
+const SYNTAX_TOKEN_VARS = [
+    ['--oc-syntax-keyword', '--syntax-keyword', 'syntaxKeyword'],
+    ['--oc-syntax-string', '--syntax-string', 'syntaxString'],
+    ['--oc-syntax-number', '--syntax-number', 'syntaxNumber'],
+    ['--oc-syntax-function', '--syntax-function', 'syntaxFunction'],
+    ['--oc-syntax-type', '--syntax-type', 'syntaxType'],
+    ['--oc-syntax-comment', '--syntax-comment', 'syntaxComment'],
+    ['--oc-syntax-variable', '--syntax-variable', 'syntaxVariable'],
+    ['--oc-syntax-operator', '--syntax-operator', 'syntaxOperator'],
+];
 /**
  * Paint the host theme onto the iframe root. Guest chrome reads these
  * variables, and the root itself gets the host font and text colour so plain
@@ -65,6 +75,11 @@ export const applyHostTheme = (theme, root) => {
     for (const [name, key] of TOKEN_VARS) {
         root.style.setProperty(name, theme.tokens[key]);
     }
+    for (const [alias, hostName, key] of SYNTAX_TOKEN_VARS) {
+        const value = theme.tokens[key] ?? '';
+        root.style.setProperty(alias, value);
+        root.style.setProperty(hostName, value);
+    }
     root.style.setProperty('font-family', theme.tokens.font);
     root.style.setProperty('font-size', '0.875rem');
     root.style.setProperty('line-height', '1.45');

package/dist/workspace-schemas.d.ts

@@ -104,15 +104,31 @@ export declare const guestSessionWorktreeSchema: z.ZodUnion<readonly [z.ZodBoole
 export declare const guestStorageRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     op: z.ZodLiteral<"get">;
     key: z.ZodString;
+    scope: z.ZodOptional<z.ZodEnum<{
+        instance: "instance";
+        device: "device";
+    }>>;
 }, z.core.$strict>, z.ZodObject<{
     op: z.ZodLiteral<"delete">;
     key: z.ZodString;
+    scope: z.ZodOptional<z.ZodEnum<{
+        instance: "instance";
+        device: "device";
+    }>>;
 }, z.core.$strict>, z.ZodObject<{
     op: z.ZodLiteral<"set">;
     key: z.ZodString;
     value: z.ZodJSONSchema;
+    scope: z.ZodOptional<z.ZodEnum<{
+        instance: "instance";
+        device: "device";
+    }>>;
 }, z.core.$strict>, z.ZodObject<{
     op: z.ZodLiteral<"keys">;
+    scope: z.ZodOptional<z.ZodEnum<{
+        instance: "instance";
+        device: "device";
+    }>>;
 }, z.core.$strict>], "op">;
 export declare const guestStorageResultSchema: z.ZodUnion<readonly [z.ZodObject<{
     storage: z.ZodLiteral<true>;

package/dist/workspace-schemas.js

@@ -31,10 +31,10 @@ export const guestSessionWorktreeSchema = z.union([
 ]);
 const storageKey = z.string().min(1).max(GUEST_STORAGE_KEY_MAX);
 export const guestStorageRequestSchema = z.discriminatedUnion('op', [
-    z.object({ op: z.literal('get'), key: storageKey }).strict(),
-    z.object({ op: z.literal('delete'), key: storageKey }).strict(),
-    z.object({ op: z.literal('set'), key: storageKey, value: z.json().refine((value) => new TextEncoder().encode(JSON.stringify(value)).length <= GUEST_STORAGE_VALUE_BYTES) }).strict(),
-    z.object({ op: z.literal('keys') }).strict(),
+    z.object({ op: z.literal('get'), key: storageKey, scope: z.enum(['instance', 'device']).optional() }).strict(),
+    z.object({ op: z.literal('delete'), key: storageKey, scope: z.enum(['instance', 'device']).optional() }).strict(),
+    z.object({ op: z.literal('set'), key: storageKey, value: z.json().refine((value) => new TextEncoder().encode(JSON.stringify(value)).length <= GUEST_STORAGE_VALUE_BYTES), scope: z.enum(['instance', 'device']).optional() }).strict(),
+    z.object({ op: z.literal('keys'), scope: z.enum(['instance', 'device']).optional() }).strict(),
 ]);
 export const guestStorageResultSchema = z.union([
     z.object({ storage: z.literal(true), op: z.literal('get'), found: z.literal(false) }),

package/dist/workspace.d.ts

@@ -74,17 +74,23 @@ export type GuestWorkspaceUpdate = {
 export declare const GUEST_STORAGE_KEY_MAX = 128;
 export declare const GUEST_STORAGE_VALUE_BYTES = 65536;
 export declare const GUEST_STORAGE_TOTAL_BYTES = 2097152;
+/** Maximum bytes retained across all device-scoped guest storage namespaces. */
+export declare const GUEST_DEVICE_STORAGE_TOTAL_BYTES = 16777216;
 export declare const GUEST_STORAGE_KEYS_MAX = 2000;
-export type GuestStorageRequest = {
+export type GuestStorageScope = 'instance' | 'device';
+export type GuestStorageOptions = {
+    scope?: GuestStorageScope;
+};
+export type GuestStorageRequest = ({
     op: 'get' | 'delete';
     key: string;
-} | {
+} & GuestStorageOptions) | ({
     op: 'set';
     key: string;
     value: JsonValue;
-} | {
+} & GuestStorageOptions) | ({
     op: 'keys';
-};
+} & GuestStorageOptions);
 export type GuestStorageResult = {
     storage: true;
 } & ({

package/dist/workspace.js

@@ -1,4 +1,6 @@
 export const GUEST_STORAGE_KEY_MAX = 128;
 export const GUEST_STORAGE_VALUE_BYTES = 65_536;
 export const GUEST_STORAGE_TOTAL_BYTES = 2_097_152;
+/** Maximum bytes retained across all device-scoped guest storage namespaces. */
+export const GUEST_DEVICE_STORAGE_TOTAL_BYTES = 16_777_216;
 export const GUEST_STORAGE_KEYS_MAX = 2_000;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openchamber/sdk",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Contract for OpenChamber guests: manifest parse and iframe host bridge.",
   "private": false,
   "license": "MIT",