@ggui-ai/protocol 0.1.0-rc.1

package/dist/types/interface-context.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Interface Context — device and viewport information for responsive UI generation.
+ *
+ * Threaded through the full pipeline:
+ * Client → WebSocket/MCP → SQS → Queue Consumer → Generator → Prompts
+ *
+ * Allows Claude to generate UIs adapted to the user's device/viewport.
+ */
+import type { JsonObject } from './data-contract';
+export type PlatformType = 'web' | 'mobile' | 'desktop';
+export type DeviceType = 'phone' | 'tablet' | 'desktop';
+export type Orientation = 'portrait' | 'landscape';
+/**
+ * Device category for blueprint variant selection.
+ * Each blueprint can have optimized variants per device category.
+ *
+ * - mobile: viewport width < 768px
+ * - tablet: viewport width 768-1023px
+ * - desktop: viewport width >= 1024px
+ * - spatial: 3D spatial shell (overrides width-based detection)
+ */
+export type DeviceCategory = 'mobile' | 'tablet' | 'desktop' | 'spatial';
+/**
+ * Shell type — describes the rendering container for generated UI.
+ * The generator uses this to adapt layout, sizing, and interaction patterns.
+ *
+ * - chat: Inline card in a scrolling chat conversation. Compact, card-sized.
+ * - fullscreen: Full-viewport swipeable card. Fill entire screen, immersive.
+ * - agent: Character-based shell (R2D2-style). Screen panel + character + thinking bubble.
+ * - spatial: 3D spatial panel (future: Meta Glass, Apple Vision Pro). Fixed-size floating panel.
+ */
+export type ShellType = 'chat' | 'fullscreen' | 'agent' | 'spatial';
+/**
+ * Viewport dimensions in CSS pixels.
+ * Used for responsive breakpoint calculations and layout decisions.
+ *
+ * Extends {@link JsonObject} for direct JSON serialization over WebSocket.
+ */
+export interface ViewportInfo extends JsonObject {
+    /** Width in CSS pixels */
+    width: number;
+    /** Height in CSS pixels */
+    height: number;
+}
+/**
+ * Complete interface context describing the rendering environment.
+ * All fields except viewport are optional for graceful degradation.
+ *
+ * Extends {@link JsonObject} for direct JSON serialization over WebSocket.
+ */
+export interface InterfaceContext extends JsonObject {
+    /** Viewport dimensions in CSS pixels */
+    viewport: ViewportInfo;
+    /** Platform type */
+    platform: PlatformType;
+    /** Device form factor */
+    deviceType: DeviceType;
+    /** Screen orientation */
+    orientation: Orientation;
+    /** Device pixel ratio (for high-DPI rendering decisions) */
+    devicePixelRatio?: number;
+    /** Whether touch is the primary input method */
+    touchPrimary?: boolean;
+    /**
+     * Shell type — the rendering container for this UI.
+     * Tells the generator how the component will be displayed so it can
+     * adapt layout, sizing, spacing, and interaction patterns accordingly.
+     */
+    shellType?: ShellType;
+    /** User's preferred color scheme */
+    colorScheme?: 'light' | 'dark';
+    /** Whether the user prefers reduced motion (prefers-reduced-motion) */
+    reducedMotion?: boolean;
+}
+/**
+ * Detect interface context from the browser `window` object.
+ *
+ * Reads viewport size, device pixel ratio, touch capability, color scheme,
+ * and reduced-motion preference. Falls back to {@link defaultInterfaceContext}
+ * when called in a non-browser environment (e.g., SSR).
+ *
+ * @returns Fully populated interface context derived from the browser
+ */
+export declare function detectInterfaceContext(): InterfaceContext;
+/**
+ * Default interface context for SSR or when browser detection is unavailable.
+ *
+ * Returns a standard desktop viewport (1280x800), landscape orientation,
+ * non-touch, 1x pixel ratio. Suitable as a safe fallback for server-side
+ * rendering where no `window` object exists.
+ *
+ * @returns A desktop-oriented default context
+ */
+export declare function defaultInterfaceContext(): InterfaceContext;
+/**
+ * Derive the device category from an InterfaceContext.
+ * Used for blueprint variant selection — determines which optimized
+ * version of a blueprint to serve.
+ *
+ * Priority:
+ * 1. If shellType is 'spatial', returns 'spatial' (overrides width)
+ * 2. Otherwise, derives from viewport width using standard breakpoints
+ */
+export declare function getDeviceCategory(context: InterfaceContext): DeviceCategory;
+//# sourceMappingURL=interface-context.d.ts.map

package/dist/types/interface-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interface-context.d.ts","sourceRoot":"","sources":["../../src/types/interface-context.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAMlD,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,QAAQ,GAAG,SAAS,CAAC;AACxD,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;AACxD,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,WAAW,CAAC;AAEnD;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;AAEzE;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,YAAY,GAAG,OAAO,GAAG,SAAS,CAAC;AAEpE;;;;;GAKG;AACH,MAAM,WAAW,YAAa,SAAQ,UAAU;IAC9C,0BAA0B;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAiB,SAAQ,UAAU;IAClD,wCAAwC;IACxC,QAAQ,EAAE,YAAY,CAAC;IACvB,oBAAoB;IACpB,QAAQ,EAAE,YAAY,CAAC;IACvB,yBAAyB;IACzB,UAAU,EAAE,UAAU,CAAC;IACvB,yBAAyB;IACzB,WAAW,EAAE,WAAW,CAAC;IACzB,4DAA4D;IAC5D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gDAAgD;IAChD,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,oCAAoC;IACpC,WAAW,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC/B,uEAAuE;IACvE,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAMD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,IAAI,gBAAgB,CAuBzD;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,IAAI,gBAAgB,CAS1D;AAMD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,gBAAgB,GAAG,cAAc,CAU3E"}

package/dist/types/interface-context.js

@@ -0,0 +1,115 @@
+/**
+ * Interface Context — device and viewport information for responsive UI generation.
+ *
+ * Threaded through the full pipeline:
+ * Client → WebSocket/MCP → SQS → Queue Consumer → Generator → Prompts
+ *
+ * Allows Claude to generate UIs adapted to the user's device/viewport.
+ */
+// =============================================================================
+// Detection & Defaults
+// =============================================================================
+/**
+ * Detect interface context from the browser `window` object.
+ *
+ * Reads viewport size, device pixel ratio, touch capability, color scheme,
+ * and reduced-motion preference. Falls back to {@link defaultInterfaceContext}
+ * when called in a non-browser environment (e.g., SSR).
+ *
+ * @returns Fully populated interface context derived from the browser
+ */
+export function detectInterfaceContext() {
+    if (typeof window === 'undefined') {
+        return defaultInterfaceContext();
+    }
+    const width = window.innerWidth;
+    const height = window.innerHeight;
+    const devicePixelRatio = window.devicePixelRatio || 1;
+    const touchPrimary = 'ontouchstart' in window || navigator.maxTouchPoints > 0;
+    const colorScheme = window.matchMedia?.('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+    const reducedMotion = window.matchMedia?.('(prefers-reduced-motion: reduce)').matches ?? false;
+    return {
+        viewport: { width, height },
+        platform: detectPlatform(touchPrimary),
+        deviceType: detectDeviceType(width),
+        orientation: width >= height ? 'landscape' : 'portrait',
+        devicePixelRatio,
+        touchPrimary,
+        colorScheme,
+        reducedMotion,
+    };
+}
+/**
+ * Default interface context for SSR or when browser detection is unavailable.
+ *
+ * Returns a standard desktop viewport (1280x800), landscape orientation,
+ * non-touch, 1x pixel ratio. Suitable as a safe fallback for server-side
+ * rendering where no `window` object exists.
+ *
+ * @returns A desktop-oriented default context
+ */
+export function defaultInterfaceContext() {
+    return {
+        viewport: { width: 1280, height: 800 },
+        platform: 'web',
+        deviceType: 'desktop',
+        orientation: 'landscape',
+        devicePixelRatio: 1,
+        touchPrimary: false,
+    };
+}
+// =============================================================================
+// Device Category
+// =============================================================================
+/**
+ * Derive the device category from an InterfaceContext.
+ * Used for blueprint variant selection — determines which optimized
+ * version of a blueprint to serve.
+ *
+ * Priority:
+ * 1. If shellType is 'spatial', returns 'spatial' (overrides width)
+ * 2. Otherwise, derives from viewport width using standard breakpoints
+ */
+export function getDeviceCategory(context) {
+    if (context.shellType === 'spatial') {
+        return 'spatial';
+    }
+    const width = context.viewport.width;
+    if (width < 768)
+        return 'mobile';
+    if (width < 1024)
+        return 'tablet';
+    return 'desktop';
+}
+// =============================================================================
+// Internal Helpers
+// =============================================================================
+/**
+ * Infer the platform type from the user agent string and touch capability.
+ *
+ * @param touchPrimary - Whether touch is the primary input method
+ * @returns Detected platform: `'mobile'` for phones/tablets, `'web'` otherwise
+ */
+function detectPlatform(touchPrimary) {
+    if (typeof navigator === 'undefined')
+        return 'web';
+    const ua = navigator.userAgent.toLowerCase();
+    if (ua.includes('android') || ua.includes('iphone') || ua.includes('ipad'))
+        return 'mobile';
+    if (touchPrimary && ua.includes('mobile'))
+        return 'mobile';
+    return 'web';
+}
+/**
+ * Classify device form factor from viewport width using standard breakpoints.
+ *
+ * @param width - Viewport width in CSS pixels
+ * @returns `'phone'` (<768px), `'tablet'` (768-1023px), or `'desktop'` (>=1024px)
+ */
+function detectDeviceType(width) {
+    if (width < 768)
+        return 'phone';
+    if (width < 1024)
+        return 'tablet';
+    return 'desktop';
+}

package/dist/types/invoke.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Streamable Invoke Protocol v1 — TypeScript types.
+ *
+ * Derived from Zod schemas in schemas/invoke.ts via z.infer — single source
+ * of truth. Do not hand-author parallel types here.
+ */
+import type { z } from 'zod';
+import type { textBlockSchema, toolUseBlockSchema, toolResultBlockSchema, contentBlockSchema, textDeltaSchema, inputJsonDeltaSchema, contentBlockDeltaPayloadSchema, messageStartEventSchema, contentBlockStartEventSchema, contentBlockDeltaEventSchema, contentBlockStopEventSchema, messageDeltaEventSchema, messageStopEventSchema, pingEventSchema, errorEventSchema, invokeEventSchema, invokeErrorCodeSchema, invokeTurnSchema, invokeRequestSchema } from '../schemas/invoke';
+export type TextBlock = z.infer<typeof textBlockSchema>;
+export type ToolUseBlock = z.infer<typeof toolUseBlockSchema>;
+export type ToolResultBlock = z.infer<typeof toolResultBlockSchema>;
+export type ContentBlock = z.infer<typeof contentBlockSchema>;
+export type TextDelta = z.infer<typeof textDeltaSchema>;
+export type InputJsonDelta = z.infer<typeof inputJsonDeltaSchema>;
+export type ContentBlockDeltaPayload = z.infer<typeof contentBlockDeltaPayloadSchema>;
+export type MessageStartEvent = z.infer<typeof messageStartEventSchema>;
+export type ContentBlockStartEvent = z.infer<typeof contentBlockStartEventSchema>;
+export type ContentBlockDeltaEvent = z.infer<typeof contentBlockDeltaEventSchema>;
+export type ContentBlockStopEvent = z.infer<typeof contentBlockStopEventSchema>;
+export type MessageDeltaEvent = z.infer<typeof messageDeltaEventSchema>;
+export type MessageStopEvent = z.infer<typeof messageStopEventSchema>;
+export type PingEvent = z.infer<typeof pingEventSchema>;
+export type ErrorEvent = z.infer<typeof errorEventSchema>;
+export type InvokeEvent = z.infer<typeof invokeEventSchema>;
+export type InvokeErrorCode = z.infer<typeof invokeErrorCodeSchema>;
+export type InvokeTurn = z.infer<typeof invokeTurnSchema>;
+export type InvokeRequest = z.infer<typeof invokeRequestSchema>;
+//# sourceMappingURL=invoke.d.ts.map

package/dist/types/invoke.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoke.d.ts","sourceRoot":"","sources":["../../src/types/invoke.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAEV,eAAe,EACf,kBAAkB,EAClB,qBAAqB,EACrB,kBAAkB,EAElB,eAAe,EACf,oBAAoB,EACpB,8BAA8B,EAE9B,uBAAuB,EACvB,4BAA4B,EAC5B,4BAA4B,EAC5B,2BAA2B,EAC3B,uBAAuB,EACvB,sBAAsB,EACtB,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,EAErB,gBAAgB,EAChB,mBAAmB,EACpB,MAAM,mBAAmB,CAAC;AAG3B,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AACxD,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACpE,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAG9D,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AACxD,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAClE,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAGtF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AACxE,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAClF,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAClF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAChF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AACxE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AACtE,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AACxD,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC1D,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC5D,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAGpE,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC1D,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC"}

package/dist/types/invoke.js

@@ -0,0 +1,7 @@
+/**
+ * Streamable Invoke Protocol v1 — TypeScript types.
+ *
+ * Derived from Zod schemas in schemas/invoke.ts via z.infer — single source
+ * of truth. Do not hand-author parallel types here.
+ */
+export {};