@simpleplatform/sdk 1.2.0 → 2.0.0

package/README.md

@@ -40,6 +40,96 @@ The TypeScript SDK is organized into focused modules for different capabilities:
 | **Security** | `@simpleplatform/sdk/security` | Security policy authoring                      |
 | **Settings** | `@simpleplatform/sdk/settings` | Application settings retrieval                 |
 | **Storage**  | `@simpleplatform/sdk/storage`  | File upload and management                     |
+| **Space**    | `@simpleplatform/sdk/space`    | Behavior-aware record workflows in a Space     |
+
+## Embedded Spaces
+
+Use the explicit Space subpaths inside an embedded browser Space. The package
+root remains the Action/WASM API, so Action code never imports browser globals
+by accident.
+
+```typescript
+import { connectSpace } from '@simpleplatform/sdk/space'
+
+const hostOrigin = new URL(document.referrer).origin
+const simple = await connectSpace({ targetOrigin: hostOrigin })
+const record = await simple.records.current()
+
+await record.update({ first_name: 'Ada' }) // Stages values and runs update Behavior.
+const result = await record.submit() // Runs submit Behavior, then persists on success.
+
+if (!result.ok) {
+  const { errors, fields } = record.snapshot()
+  // Render every field's error/info plus form-level errors.
+}
+```
+
+Connect once when the Space starts and reuse the returned client. One embedded iframe has one host MessagePort handshake.
+
+`records.current()` returns the platform-owned record for the current record
+page. Its handle exposes immutable snapshots, `update(values)`, and `submit()`.
+The host enforces permissions and runs Record Behaviors; the Space only renders
+the returned state.
+
+### Space context
+
+`simple.context` is explicit host-provided page context. It is never inferred
+from a Space URL or the iframe DOM.
+
+```ts
+switch (simple.context.kind) {
+  case 'standalone':
+    break
+  case 'record':
+    console.log(
+      simple.context.applicationId,
+      simple.context.tableName,
+      simple.context.recordId,
+    )
+    break
+}
+```
+
+The two exact context forms are `{ kind: 'standalone' }` and
+`{ kind: 'record', applicationId, tableName, recordId }`. There is no
+`unknown` context variant. A missing or malformed context rejects
+`connectSpace()` with `SpaceProtocolError` code `invalid_response`.
+
+`connectSpace()` works in any embedded Space, including standalone dashboards
+and tools. In a non-record Space, `simple.data` remains available while
+`simple.records.current()` rejects with `SpaceProtocolError` code `unavailable`
+and explains that the Space must be configured as a record view.
+
+### Space data access
+
+Use `simple.data` for application data that is not the record form currently
+being edited. It uses the Space's existing, host-authorized GraphQL bridge.
+
+```typescript
+const users = await simple.data.query<{ users: Array<{ id: string, email: string }> }>(
+  `query ListUsers($limit: Int!) {
+    users: dev_simple_system__users(limit: $limit) {
+      id
+      email
+    }
+  }`,
+  { limit: 10 },
+)
+
+const result = await simple.data.mutate<{ insert_demo__note: { id: string } }>(
+  `mutation CreateNote($body: String!) {
+    insert_demo__note(object: { body: $body }) {
+      id
+    }
+  }`,
+  { body: 'Follow up with the customer.' },
+)
+```
+
+Use `record.update()` and `record.submit()` for writes to the current record.
+Those commands preserve Record Behaviors, validation, documents, and the shared
+record state used by the platform header. `simple.data.mutate()` is for other
+authorized application data; it must not be used to bypass a record workflow.
 
 ---
 

package/dist/ai.js

@@ -266,21 +266,6 @@ export async function transcribe(input, options, context) {
 // ============================================================================
 // Face Recognition API
 // ============================================================================
-let _collectionEnsured = false;
-/**
- * Internal helper to ensure the face collection exists before making face operations.
- * Caches the result per Javascript isolate execution to minimize RPC overhead over
- * sequential calls in the same logic.
- */
-async function _ensureFaceCollection(context) {
-    if (_collectionEnsured)
-        return;
-    const response = await hostExecute('action:ai/face/ensure-collection', {}, context);
-    if (!response.ok) {
-        throw new Error(response.error?.message || 'Failed to ensure face collection.');
-    }
-    _collectionEnsured = true;
-}
 /**
  * Enrolls a face for a subject. The face is associated with the given `subjectId`
  * within the tenant's secure collection.
@@ -298,9 +283,7 @@ export async function enrollFace(subjectId, image, context) {
     if (!image) {
         throw new Error('The `image` parameter is required for `enrollFace`.');
     }
-    // Ensure the tenant's collection is ready before enrolling
-    await _ensureFaceCollection(context);
-    // Upload pending documents if given handles
+    // Upload pending DocumentHandles to ephemeral storage
     const processedImage = await _uploadPendingFiles(image, context);
     const payload = {
         image: processedImage,
@@ -325,8 +308,6 @@ export async function searchFace(image, options = {}, context) {
     if (!image) {
         throw new Error('The `image` parameter is required for `searchFace`.');
     }
-    // Ensure collection exists before searching
-    await _ensureFaceCollection(context);
     const processedImage = await _uploadPendingFiles(image, context);
     // Map JS property names to Elixir convention if needed, though they are passed as options
     // and parsed correctly in simple_logic if expected.
@@ -358,7 +339,6 @@ export async function deleteFace(faceIds, context) {
     if (!faceIds || !Array.isArray(faceIds) || faceIds.length === 0) {
         throw new Error('The `faceIds` parameter must be a non-empty array for `deleteFace`.');
     }
-    await _ensureFaceCollection(context);
     const payload = {
         face_ids: faceIds,
     };

package/dist/graphql.js

@@ -18,8 +18,6 @@ export async function execute(query, variables, context) {
     if (!response.ok) {
         // eslint-disable-next-line no-console
         console.log('[GraphQL] response.error:', JSON.stringify(response.error, null, 2));
-        // eslint-disable-next-line no-console
-        console.log('[GraphQL] response.data:', JSON.stringify(response.data, null, 2));
         throw new Error(response.error?.message ?? 'GraphQL query failed');
     }
     return response.data;

package/dist/host.d.ts

@@ -1,28 +1,17 @@
 import type { Context, SimpleResponse } from './types';
 /**
- * Executes an action synchronously on the host system and returns the response.
+ * Calls an action on the host and returns its response.
  *
- * NOTE: The memory model for this execution is that the entire WASM instance is
- * ephemeral. Memory is allocated for this single execution and then discarded
- * when the instance is terminated. Therefore, a manual memory reset is not required.
- *
- * This function has two internal implementations selected at build time:
- * 1. ASYNC_BUILD = true: For browsers, uses Asyncify to pause/resume execution.
- * 2. ASYNC_BUILD = false: For Elixir, uses a synchronous call-and-get-result pattern.
+ * The runtime owns serialization and memory for this boundary. The SDK passes
+ * the action name and parameters as JavaScript values, and the host returns the
+ * parsed response as a value.
  */
 export declare function execute<T = any>(actionName: string, params: any, context: Context): SimpleResponse<T>;
 /**
- * Executes an action asynchronously on the host system (fire-and-forget).
+ * Calls an action on the host without waiting for it to answer.
  */
 export declare function executeAsync(actionName: string, params: any, context: Context): void;
 /**
- * Retrieves the initial context payload from the host. This function orchestrates
- * the "pull" mechanism required by the execution environment.
- *
- * It first asks the host for the payload size, then allocates memory within
- * the WASM module, and finally asks the host to write the payload into the
- * allocated buffer.
- *
- * @returns A Uint8Array containing the context payload.
+ * Returns the execution context the host assembled for this run.
  */
-export declare function getContext(): Uint8Array;
+export declare function getContext(): any;

package/dist/host.js

@@ -1,148 +1,40 @@
-import { allocate, deallocate, decoder, readBufferSlice, stringToPtr } from './internal/memory';
+const ABI_MISMATCH_MESSAGE = 'Simple SDK 2.0.0 requires the value-based runtime ABI: __host.call and __host.cast accept values, and __host.getContext returns the execution context. Install a runtime plugin released with the matching SDK.';
+function assertRuntimeAbi() {
+    const host = globalThis.__host;
+    const hasValueBridge = typeof host?.call === 'function'
+        && typeof host.cast === 'function'
+        && typeof host.getContext === 'function';
+    const hasLegacyBridge = typeof host?.getContextSize === 'function'
+        || typeof host?.getExecutionResult === 'function'
+        || typeof host?.getExecutionResultSize === 'function';
+    if (!hasValueBridge || hasLegacyBridge) {
+        throw new Error(ABI_MISMATCH_MESSAGE);
+    }
+}
 /**
- * Executes an action synchronously on the host system and returns the response.
- *
- * NOTE: The memory model for this execution is that the entire WASM instance is
- * ephemeral. Memory is allocated for this single execution and then discarded
- * when the instance is terminated. Therefore, a manual memory reset is not required.
+ * Calls an action on the host and returns its response.
  *
- * This function has two internal implementations selected at build time:
- * 1. ASYNC_BUILD = true: For browsers, uses Asyncify to pause/resume execution.
- * 2. ASYNC_BUILD = false: For Elixir, uses a synchronous call-and-get-result pattern.
+ * The runtime owns serialization and memory for this boundary. The SDK passes
+ * the action name and parameters as JavaScript values, and the host returns the
+ * parsed response as a value.
  */
 export function execute(actionName, params, context) {
-    // We must track the pointers for the parameters so we can free them after the call.
-    // They are declared here to be accessible in the `finally` block.
-    let actionNamePtr = 0;
-    let actionNameLen = 0;
-    let paramsPtr = 0;
-    let paramsLen = 0;
-    let contextPtr = 0;
-    let contextLen = 0;
-    try {
-        const paramsJSON = JSON.stringify(params ?? null);
-        const contextJSON = JSON.stringify(context);
-        [actionNamePtr, actionNameLen] = stringToPtr(actionName);
-        [paramsPtr, paramsLen] = stringToPtr(paramsJSON);
-        [contextPtr, contextLen] = stringToPtr(contextJSON);
-        if (__ASYNC_BUILD__) {
-            // --- ASYNCIFY-AWARE PATH (FOR BROWSER) ---
-            let responsePtr = 0;
-            let responseLen = 0;
-            try {
-                // State 2 is "Rewinding". This check implements the stateful "double call"
-                // pattern required by Asyncify.
-                if (asyncify_get_state() === 2) {
-                    // This is the second call, during the rewind. We just need to stop the
-                    // rewind so that normal execution can resume.
-                    asyncify_stop_rewind();
-                }
-                else {
-                    // This is the first call. Call the host to start the async operation.
-                    // The host will then trigger the unwind.
-                    __host.call(actionNamePtr, actionNameLen, paramsPtr, paramsLen, contextPtr, contextLen);
-                }
-                // --- EXECUTION PAUSES HERE OR CONTINUES AFTER REWIND IS STOPPED ---
-                // The host has placed the response in memory. Read it using pointers
-                // retrieved from the Javy plugin.
-                responsePtr = __wasm.get_response_ptr();
-                responseLen = __wasm.get_response_len();
-                const resultBytes = readBufferSlice(responsePtr, responseLen);
-                const resultJSON = decoder.decode(resultBytes);
-                // Immediately clear the response buffer pointers in the Javy plugin to
-                // prevent reading stale data on subsequent nested calls.
-                __wasm.clear_response_buffer();
-                return JSON.parse(resultJSON);
-            }
-            finally {
-                // 1. Free the result buffer allocated by the host.
-                if (responsePtr > 0) {
-                    deallocate(responsePtr, responseLen);
-                }
-            }
-        }
-        else {
-            // --- SYNCHRONOUS PATH (FOR ELIXIR BACKEND) ---
-            let resultPtr = 0;
-            let resultLen = 0;
-            try {
-                // 1. Make the synchronous call. The host now holds the result.
-                __host.call(actionNamePtr, actionNameLen, paramsPtr, paramsLen, contextPtr, contextLen);
-                // 2. Ask the host for the size of the result.
-                resultLen = __host.getExecutionResultSize();
-                if (resultLen === 0) {
-                    return { error: { message: 'Host returned an empty result.' }, ok: false };
-                }
-                // 3. Allocate memory inside WASM for the result.
-                resultPtr = allocate(resultLen);
-                // 4. Ask the host to write the result into our buffer.
-                __host.getExecutionResult(resultPtr);
-                // 5. Read the result from our buffer and return it.
-                const resultBytes = readBufferSlice(resultPtr, resultLen);
-                const resultJSON = decoder.decode(resultBytes);
-                return JSON.parse(resultJSON);
-            }
-            finally {
-                // Free the result buffer allocated by us.
-                if (resultPtr > 0) {
-                    deallocate(resultPtr, resultLen);
-                }
-            }
-        }
-    }
-    finally {
-        // 2. Free the parameter buffers we allocated before the host call.
-        if (actionNamePtr > 0) {
-            deallocate(actionNamePtr, actionNameLen);
-        }
-        if (paramsPtr > 0) {
-            deallocate(paramsPtr, paramsLen);
-        }
-        if (contextPtr > 0) {
-            deallocate(contextPtr, contextLen);
-        }
-    }
+    assertRuntimeAbi();
+    void context;
+    return __host.call(actionName, params ?? null);
 }
 /**
- * Executes an action asynchronously on the host system (fire-and-forget).
+ * Calls an action on the host without waiting for it to answer.
  */
 export function executeAsync(actionName, params, context) {
-    const paramsJSON = JSON.stringify(params ?? null);
-    const contextJSON = JSON.stringify(context);
-    const [actionNamePtr, actionNameLen] = stringToPtr(actionName);
-    const [paramsPtr, paramsLen] = stringToPtr(paramsJSON);
-    const [contextPtr, contextLen] = stringToPtr(contextJSON);
-    // Make the asynchronous (fire-and-forget) call to the host.
-    __host.cast(actionNamePtr, actionNameLen, paramsPtr, paramsLen, contextPtr, contextLen);
+    assertRuntimeAbi();
+    void context;
+    __host.cast(actionName, params ?? null);
 }
 /**
- * Retrieves the initial context payload from the host. This function orchestrates
- * the "pull" mechanism required by the execution environment.
- *
- * It first asks the host for the payload size, then allocates memory within
- * the WASM module, and finally asks the host to write the payload into the
- * allocated buffer.
- *
- * @returns A Uint8Array containing the context payload.
+ * Returns the execution context the host assembled for this run.
  */
 export function getContext() {
-    // Ask the host for the size of the data.
-    const size = __host.getContextSize();
-    if (size === 0) {
-        return new Uint8Array(0);
-    }
-    // Allocate memory for the data inside the WASM module's buffer.
-    const ptr = allocate(size);
-    let buffer;
-    try {
-        // Ask the host to write the data into the allocated memory region.
-        __host.getContext(ptr);
-        // Now that the data is in our memory, create a slice to read it.
-        buffer = readBufferSlice(ptr, size);
-    }
-    finally {
-        // Free the memory we allocated now that the data is in a JS-owned buffer.
-        deallocate(ptr, size);
-    }
-    return buffer;
+    assertRuntimeAbi();
+    return __host.getContext();
 }

package/dist/internal/polyfills.js

@@ -37,30 +37,38 @@ export class TextDecoder {
         let string = '';
         let i = 0;
         while (i < octets.length) {
-            let octet = octets[i];
+            // `i < octets.length` already bounds this read; the explicit guard is what
+            // narrows the element type away from `undefined` for the arithmetic below.
+            const leadingOctet = octets[i];
+            if (leadingOctet === undefined)
+                break;
             let bytesNeeded = 0;
             let codePoint = 0;
-            if (octet <= 0x7F) {
+            if (leadingOctet <= 0x7F) {
                 bytesNeeded = 0;
-                codePoint = octet & 0xFF;
+                codePoint = leadingOctet & 0xFF;
             }
-            else if (octet <= 0xDF) {
+            else if (leadingOctet <= 0xDF) {
                 bytesNeeded = 1;
-                codePoint = octet & 0x1F;
+                codePoint = leadingOctet & 0x1F;
             }
-            else if (octet <= 0xEF) {
+            else if (leadingOctet <= 0xEF) {
                 bytesNeeded = 2;
-                codePoint = octet & 0x0F;
+                codePoint = leadingOctet & 0x0F;
             }
-            else if (octet <= 0xF4) {
+            else if (leadingOctet <= 0xF4) {
                 bytesNeeded = 3;
-                codePoint = octet & 0x07;
+                codePoint = leadingOctet & 0x07;
             }
             if (octets.length - i - bytesNeeded > 0) {
                 let k = 0;
                 while (k < bytesNeeded) {
-                    octet = octets[i + k + 1];
-                    codePoint = (codePoint << 6) | (octet & 0x3F);
+                    // The branch condition guarantees `i + bytesNeeded < octets.length`,
+                    // and `k < bytesNeeded`, so this index is always in range.
+                    const continuationOctet = octets[i + k + 1];
+                    if (continuationOctet === undefined)
+                        break;
+                    codePoint = (codePoint << 6) | (continuationOctet & 0x3F);
                     k += 1;
                 }
             }

package/dist/space/core.d.ts

@@ -0,0 +1,138 @@
+export declare const PROTOCOL_VERSION: 1;
+export type SpaceContext = {
+    applicationId: string;
+    kind: 'record';
+    recordId: string;
+    tableName: string;
+} | {
+    kind: 'standalone';
+};
+export interface RecordFieldSnapshot {
+    error: null | string;
+    info: null | string;
+    readOnly: boolean;
+    required: boolean;
+    visible: boolean;
+}
+export interface RecordFormError {
+    code: string;
+    message: string;
+}
+export interface RecordErrorSnapshot {
+    fields: Readonly<Record<string, readonly string[]>>;
+    form: readonly RecordFormError[];
+}
+export interface RecordSnapshot {
+    errors: RecordErrorSnapshot;
+    fields: Readonly<Record<string, RecordFieldSnapshot>>;
+    revision: number;
+    values: Readonly<Record<string, unknown>>;
+}
+export type GraphQLVariables = Readonly<Record<string, unknown>>;
+export interface SpaceDataTransport {
+    execute: <TResult = unknown>(document: string, variables?: GraphQLVariables) => Promise<TResult>;
+}
+export interface SimpleDataClient {
+    mutate: <TResult = unknown>(document: string, variables?: GraphQLVariables) => Promise<TResult>;
+    query: <TResult = unknown>(document: string, variables?: GraphQLVariables) => Promise<TResult>;
+}
+export interface RecordHandle {
+    readonly id: string;
+    snapshot: () => RecordSnapshot;
+    submit: () => Promise<RecordSubmitResult>;
+    update: (values: Readonly<Record<string, unknown>>) => Promise<RecordUpdateResult>;
+}
+export interface SimpleClient {
+    context: SpaceContext;
+    data: SimpleDataClient;
+    records: {
+        current: () => Promise<RecordHandle>;
+    };
+}
+export interface SpaceProtocolErrorPayload {
+    code: string;
+    details?: unknown;
+    message: string;
+}
+export declare class SpaceProtocolError extends Error {
+    readonly code: string;
+    readonly details?: unknown;
+    constructor({ code, details, message }: SpaceProtocolErrorPayload);
+}
+export interface SpaceDataErrorPayload {
+    code: string;
+    details?: unknown;
+    message: string;
+}
+export declare class SpaceDataError extends Error {
+    readonly code: string;
+    readonly details?: unknown;
+    constructor({ code, details, message }: SpaceDataErrorPayload);
+}
+export interface CurrentRecordRequest {
+    operation: 'record.current';
+    payload: Record<string, never>;
+    protocol: typeof PROTOCOL_VERSION;
+    requestId: string;
+}
+export interface CurrentRecordResult {
+    sessionId: string;
+    snapshot: RecordSnapshot;
+}
+export interface RecordUpdateRequest {
+    operation: 'record.update';
+    payload: {
+        sessionId: string;
+        values: Readonly<Record<string, unknown>>;
+    };
+    protocol: typeof PROTOCOL_VERSION;
+    requestId: string;
+}
+export interface RecordUpdateResult {
+    ok: boolean;
+    snapshot: RecordSnapshot;
+}
+export interface RecordSubmitRequest {
+    operation: 'record.submit';
+    payload: {
+        sessionId: string;
+    };
+    protocol: typeof PROTOCOL_VERSION;
+    requestId: string;
+}
+export interface RecordSubmitResult {
+    ok: boolean;
+    snapshot: RecordSnapshot;
+}
+export type ProtocolRequest = CurrentRecordRequest | RecordSubmitRequest | RecordUpdateRequest;
+export interface ProtocolSuccessResponse<TResult> {
+    ok: true;
+    protocol: typeof PROTOCOL_VERSION;
+    requestId: string;
+    result: TResult;
+}
+export interface ProtocolErrorResponse {
+    error: SpaceProtocolErrorPayload;
+    ok: false;
+    protocol: typeof PROTOCOL_VERSION;
+    requestId: string;
+}
+export type ProtocolResponse<TResult> = ProtocolErrorResponse | ProtocolSuccessResponse<TResult>;
+export interface SpaceTransport {
+    request: <TResult>(request: ProtocolRequest) => Promise<ProtocolResponse<TResult>>;
+}
+export interface SimpleClientOptions {
+    context?: SpaceContext;
+    dataTransport?: SpaceDataTransport;
+    nextRequestId?: () => string;
+    transport?: SpaceTransport;
+}
+/**
+ * Creates a framework-neutral Space client around a protocol transport.
+ *
+ * MessagePort setup is intentionally outside this factory so the same public
+ * contract can be exercised in a first-party direct adapter and in any UI
+ * framework without importing browser-specific code.
+ */
+export declare function createSimpleClient({ context, dataTransport, nextRequestId, transport, }: SimpleClientOptions): SimpleClient;
+export declare function isSpaceContext(value: unknown): value is SpaceContext;

package/dist/space/core.js

@@ -0,0 +1,226 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _ProtocolRecordHandle_nextRequestId, _ProtocolRecordHandle_transport, _ProtocolRecordHandle_snapshot;
+export const PROTOCOL_VERSION = 1;
+export class SpaceProtocolError extends Error {
+    constructor({ code, details, message }) {
+        super(message);
+        this.name = 'SpaceProtocolError';
+        this.code = code;
+        this.details = details;
+    }
+}
+export class SpaceDataError extends Error {
+    constructor({ code, details, message }) {
+        super(message);
+        this.name = 'SpaceDataError';
+        this.code = code;
+        this.details = details;
+    }
+}
+/**
+ * Creates a framework-neutral Space client around a protocol transport.
+ *
+ * MessagePort setup is intentionally outside this factory so the same public
+ * contract can be exercised in a first-party direct adapter and in any UI
+ * framework without importing browser-specific code.
+ */
+export function createSimpleClient({ context = { kind: 'standalone' }, dataTransport, nextRequestId = createRequestId, transport, }) {
+    const immutableContext = immutableSpaceContext(context);
+    return {
+        context: immutableContext,
+        data: {
+            mutate: (document, variables) => executeData(dataTransport, document, variables),
+            query: (document, variables) => executeData(dataTransport, document, variables),
+        },
+        records: {
+            async current() {
+                if (immutableContext.kind !== 'record') {
+                    throw new SpaceProtocolError({
+                        code: 'unavailable',
+                        message: 'The current record is available only when this Space is configured as a record view.',
+                    });
+                }
+                if (!transport) {
+                    throw new SpaceProtocolError({
+                        code: 'unavailable',
+                        message: 'The record protocol is unavailable for this record Space.',
+                    });
+                }
+                const request = {
+                    operation: 'record.current',
+                    payload: {},
+                    protocol: PROTOCOL_VERSION,
+                    requestId: nextRequestId(),
+                };
+                const response = await transport.request(request);
+                const result = readResponse(response, request);
+                if (!isCurrentRecordResult(result)) {
+                    throw invalidResponse('The primary-record response is malformed.');
+                }
+                return new ProtocolRecordHandle(result, nextRequestId, transport);
+            },
+        },
+    };
+}
+export function isSpaceContext(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const context = value;
+    if (context.kind === 'standalone') {
+        return true;
+    }
+    return context.kind === 'record'
+        && typeof context.applicationId === 'string'
+        && context.applicationId.length > 0
+        && typeof context.tableName === 'string'
+        && context.tableName.length > 0
+        && typeof context.recordId === 'string'
+        && context.recordId.length > 0;
+}
+function executeData(dataTransport, document, variables) {
+    if (!dataTransport) {
+        return Promise.reject(new SpaceDataError({
+            code: 'unavailable',
+            message: 'The Space data transport is unavailable.',
+        }));
+    }
+    return dataTransport.execute(document, variables);
+}
+class ProtocolRecordHandle {
+    constructor({ sessionId, snapshot }, nextRequestId, transport) {
+        _ProtocolRecordHandle_nextRequestId.set(this, void 0);
+        _ProtocolRecordHandle_transport.set(this, void 0);
+        _ProtocolRecordHandle_snapshot.set(this, void 0);
+        this.id = sessionId;
+        __classPrivateFieldSet(this, _ProtocolRecordHandle_nextRequestId, nextRequestId, "f");
+        __classPrivateFieldSet(this, _ProtocolRecordHandle_snapshot, immutableSnapshot(snapshot), "f");
+        __classPrivateFieldSet(this, _ProtocolRecordHandle_transport, transport, "f");
+    }
+    snapshot() {
+        return __classPrivateFieldGet(this, _ProtocolRecordHandle_snapshot, "f");
+    }
+    async update(values) {
+        const request = {
+            operation: 'record.update',
+            payload: {
+                sessionId: this.id,
+                values,
+            },
+            protocol: PROTOCOL_VERSION,
+            requestId: __classPrivateFieldGet(this, _ProtocolRecordHandle_nextRequestId, "f").call(this),
+        };
+        const response = await __classPrivateFieldGet(this, _ProtocolRecordHandle_transport, "f").request(request);
+        const result = readResponse(response, request);
+        if (!isRecordUpdateResult(result))
+            throw invalidResponse('The record-update response is malformed.');
+        const snapshot = immutableSnapshot(result.snapshot);
+        __classPrivateFieldSet(this, _ProtocolRecordHandle_snapshot, snapshot, "f");
+        return { ok: result.ok, snapshot };
+    }
+    async submit() {
+        const request = {
+            operation: 'record.submit',
+            payload: { sessionId: this.id },
+            protocol: PROTOCOL_VERSION,
+            requestId: __classPrivateFieldGet(this, _ProtocolRecordHandle_nextRequestId, "f").call(this),
+        };
+        const response = await __classPrivateFieldGet(this, _ProtocolRecordHandle_transport, "f").request(request);
+        const result = readResponse(response, request);
+        if (!isRecordSubmitResult(result))
+            throw invalidResponse('The record-submit response is malformed.');
+        const snapshot = immutableSnapshot(result.snapshot);
+        __classPrivateFieldSet(this, _ProtocolRecordHandle_snapshot, snapshot, "f");
+        return { ok: result.ok, snapshot };
+    }
+}
+_ProtocolRecordHandle_nextRequestId = new WeakMap(), _ProtocolRecordHandle_transport = new WeakMap(), _ProtocolRecordHandle_snapshot = new WeakMap();
+function createRequestId() {
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function')
+        return crypto.randomUUID();
+    return `space-request-${Math.random().toString(36).slice(2)}`;
+}
+function immutableSnapshot(snapshot) {
+    if (!isRecordSnapshot(snapshot))
+        throw invalidResponse('The record snapshot is malformed.');
+    return deepFreeze(structuredClone(snapshot));
+}
+function immutableSpaceContext(context) {
+    return deepFreeze(structuredClone(context));
+}
+function deepFreeze(value) {
+    if (!value || typeof value !== 'object' || Object.isFrozen(value))
+        return value;
+    for (const child of Object.values(value))
+        deepFreeze(child);
+    return Object.freeze(value);
+}
+function invalidResponse(message) {
+    return new SpaceProtocolError({ code: 'invalid_response', message });
+}
+function isCurrentRecordResult(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const result = value;
+    return typeof result.sessionId === 'string' && result.sessionId.length > 0 && isRecordSnapshot(result.snapshot);
+}
+function isRecordSnapshot(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const snapshot = value;
+    return Number.isSafeInteger(snapshot.revision)
+        && (snapshot.revision ?? -1) >= 0
+        && isRecordErrorSnapshot(snapshot.errors)
+        && isRecordFieldSnapshotMap(snapshot.fields)
+        && isObjectRecord(snapshot.values);
+}
+function isRecordUpdateResult(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const result = value;
+    return typeof result.ok === 'boolean' && isRecordSnapshot(result.snapshot);
+}
+function isRecordSubmitResult(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const result = value;
+    return typeof result.ok === 'boolean' && isRecordSnapshot(result.snapshot);
+}
+function isObjectRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function isRecordErrorSnapshot(value) {
+    if (!isObjectRecord(value) || !isObjectRecord(value.fields) || !Array.isArray(value.form))
+        return false;
+    return Object.values(value.fields).every(errors => Array.isArray(errors) && errors.every(error => typeof error === 'string'))
+        && value.form.every(error => isObjectRecord(error) && typeof error.code === 'string' && typeof error.message === 'string');
+}
+function isRecordFieldSnapshotMap(value) {
+    return isObjectRecord(value) && Object.values(value).every((field) => {
+        if (!isObjectRecord(field))
+            return false;
+        return (field.error === null || typeof field.error === 'string')
+            && (field.info === null || typeof field.info === 'string')
+            && typeof field.readOnly === 'boolean'
+            && typeof field.required === 'boolean'
+            && typeof field.visible === 'boolean';
+    });
+}
+function readResponse(response, request) {
+    if (response.protocol !== PROTOCOL_VERSION || response.requestId !== request.requestId) {
+        throw invalidResponse('The response does not match the request envelope.');
+    }
+    if (!response.ok)
+        throw new SpaceProtocolError(response.error);
+    return response.result;
+}

package/dist/space/index.d.ts

@@ -0,0 +1,33 @@
+import type { SimpleClient } from './core.js';
+import { SpaceDataError, SpaceProtocolError } from './core.js';
+export { SpaceDataError, SpaceProtocolError, };
+export type { GraphQLVariables, RecordErrorSnapshot, RecordFieldSnapshot, RecordFormError, RecordHandle, RecordSnapshot, RecordSubmitResult, RecordUpdateResult, SimpleClient, SimpleDataClient, SpaceContext, SpaceDataErrorPayload, SpaceProtocolErrorPayload, } from './core.js';
+interface MessagePortLike {
+    onmessage: null | ((event: {
+        data: unknown;
+    }) => void);
+    postMessage: (message: unknown) => void;
+    start?: () => void;
+}
+export interface SpaceWindowLike {
+    addEventListener: (type: 'message', listener: (event: SpaceMessageEvent) => void) => void;
+    parent: {
+        postMessage: (message: unknown, targetOrigin: string) => void;
+    };
+    removeEventListener: (type: 'message', listener: (event: SpaceMessageEvent) => void) => void;
+}
+export interface SpaceMessageEvent {
+    data: unknown;
+    origin: string;
+    ports: MessagePortLike[];
+}
+export interface ConnectSpaceOptions {
+    targetOrigin: string;
+    window?: SpaceWindowLike;
+}
+/**
+ * Connects any embedded Space to its parent through the dedicated MessagePort
+ * handshake. Record operations become available only when the host negotiates
+ * record protocol v1 for a configured record view.
+ */
+export declare function connectSpace({ targetOrigin, window }: ConnectSpaceOptions): Promise<SimpleClient>;

package/dist/space/index.js

@@ -0,0 +1,135 @@
+import { createSimpleClient, isSpaceContext, PROTOCOL_VERSION, SpaceDataError, SpaceProtocolError, } from './core.js';
+export { SpaceDataError, SpaceProtocolError, };
+/**
+ * Connects any embedded Space to its parent through the dedicated MessagePort
+ * handshake. Record operations become available only when the host negotiates
+ * record protocol v1 for a configured record view.
+ */
+export function connectSpace({ targetOrigin, window = globalThis.window }) {
+    if (!window) {
+        return Promise.reject(new SpaceProtocolError({
+            code: 'unavailable',
+            message: 'The Space SDK requires a browser window.',
+        }));
+    }
+    return new Promise((resolve, reject) => {
+        const onMessage = (event) => {
+            if (event.origin !== targetOrigin || !isInitializationMessage(event.data))
+                return;
+            window.removeEventListener('message', onMessage);
+            const port = event.ports[0];
+            if (!port) {
+                reject(new SpaceProtocolError({
+                    code: 'unavailable',
+                    message: 'The Space host did not provide a MessagePort.',
+                }));
+                return;
+            }
+            if (!isSpaceContext(event.data.context)) {
+                reject(new SpaceProtocolError({
+                    code: 'invalid_response',
+                    message: 'The Space host did not provide valid context.',
+                }));
+                return;
+            }
+            const transport = createMessagePortTransport(port);
+            const recordTransport = event.data.protocols?.record === PROTOCOL_VERSION
+                ? transport
+                : undefined;
+            resolve(createSimpleClient({
+                context: event.data.context,
+                dataTransport: transport,
+                transport: recordTransport,
+            }));
+        };
+        window.addEventListener('message', onMessage);
+        window.parent.postMessage({
+            protocols: { record: [PROTOCOL_VERSION] },
+            type: 'SPACE_READY',
+        }, targetOrigin);
+    });
+}
+function createMessagePortTransport(port) {
+    const pendingData = new Map();
+    const pending = new Map();
+    port.onmessage = (event) => {
+        const message = event.data;
+        if (!message || typeof message !== 'object')
+            return;
+        const envelope = message;
+        if (envelope.type === 'SPACE_PROTOCOL_RESPONSE' && envelope.response) {
+            const requestId = envelope.response.requestId;
+            const request = pending.get(requestId);
+            if (!request)
+                return;
+            pending.delete(requestId);
+            request.resolve(envelope.response);
+            return;
+        }
+        if (envelope.type !== 'GRAPHQL_RESPONSE' || typeof envelope.id !== 'string')
+            return;
+        const request = pendingData.get(envelope.id);
+        if (!request)
+            return;
+        pendingData.delete(envelope.id);
+        if (envelope.error || envelope.errors) {
+            request.reject(new SpaceDataError({
+                code: 'request_failed',
+                details: envelope.errors,
+                message: readGraphQLErrorMessage(envelope.error, envelope.errors),
+            }));
+            return;
+        }
+        request.resolve(envelope.data);
+    };
+    port.start?.();
+    return {
+        execute: (document, variables) => {
+            return new Promise((resolve, reject) => {
+                const id = createDataRequestId();
+                pendingData.set(id, { reject, resolve: result => resolve(result) });
+                port.postMessage({
+                    payload: { id, query: document, variables },
+                    type: 'GRAPHQL_REQUEST',
+                });
+            });
+        },
+        request: (request) => {
+            return new Promise((resolve) => {
+                pending.set(request.requestId, {
+                    resolve: response => resolve(response),
+                });
+                port.postMessage({ request, type: 'SPACE_PROTOCOL_REQUEST' });
+            });
+        },
+    };
+}
+function createDataRequestId() {
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function')
+        return crypto.randomUUID();
+    return `space-data-${Math.random().toString(36).slice(2)}`;
+}
+function readGraphQLErrorMessage(error, errors) {
+    if (typeof error === 'string' && error)
+        return error;
+    if (Array.isArray(errors)) {
+        const firstError = errors[0];
+        if (firstError && typeof firstError === 'object') {
+            const details = firstError;
+            const issue = details.extensions?.issues?.[0]?.message;
+            if (typeof issue === 'string' && issue)
+                return issue;
+            const message = details.extensions?.details?.message;
+            if (typeof message === 'string' && message)
+                return message;
+            if (typeof details.message === 'string' && details.message)
+                return details.message;
+        }
+    }
+    return 'GraphQL request failed.';
+}
+function isInitializationMessage(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    return value.type === 'INIT_RPC';
+}

package/dist/space/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simpleplatform/sdk",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "description": "Simple Platform Typescript SDK",
   "license": "Apache-2.0",
   "homepage": "https://docs.simple.dev",
@@ -49,6 +49,10 @@
       "types": "./dist/host.d.ts",
       "default": "./dist/host.js"
     },
+    "./space": {
+      "types": "./dist/space/index.d.ts",
+      "default": "./dist/space/index.js"
+    },
     "./worker": "./dist/worker-override.js",
     "./package.json": "./package.json"
   },
@@ -68,6 +72,8 @@
     "typescript": "5.9.3"
   },
   "scripts": {
-    "build": "rm -rf dist && tsc && cp src/worker-override.js dist/ && cp cli/build.js dist/"
+    "build": "rm -rf dist && tsc && cp src/worker-override.js dist/ && cp cli/build.js dist/ && cp src/space/package.json dist/space/",
+    "test": "pnpm run build && node --test test/*.test.mjs",
+    "typecheck": "tsc --noEmit"
   }
 }

package/dist/internal/memory.d.ts

@@ -1,103 +0,0 @@
-/**
- * @fileoverview WebAssembly Memory Management Module
- *
- * Provides a high-level interface for managing WebAssembly linear memory operations.
- * This module handles string-based data exchange between JavaScript and the WASM
- * runtime through direct UTF-8 operations, avoiding unnecessary serialization overhead.
- *
- * ## Architecture
- *
- * The memory bridge operates on two main principles:
- * - **Direct String Operations**: Strings are passed directly between JS and WASM
- * - **UTF-8 Encoding**: All string data is handled as UTF-8 encoded bytes
- *
- * ## Usage
- *
- * ```typescript
- * // Allocate memory for a string
- * const [ptr, len] = stringToPtr("Hello, World!")
- *
- * // Read data back from memory
- * const data = readBufferSlice(ptr, len)
- * ```
- */
-/** Reusable TextDecoder instance for UTF-8 string decoding. */
-export declare const decoder: TextDecoder;
-/**
- * Allocates a block of memory within the WebAssembly linear memory space.
- *
- * This function provides the primary interface for requesting memory from
- * the WASM module's allocator. The returned pointer can be used for
- * subsequent read/write operations.
- *
- * @param size - Number of bytes to allocate
- * @returns Memory pointer (offset) to the allocated block
- *
- * @example
- * ```typescript
- * const ptr = allocate(1024) // Allocate 1KB
- * ```
- */
-export declare function allocate(size: number): number;
-/**
- *
- * @param ptr - Memory pointer to deallocate
- * @param size -  Number of bytes to deallocate
- *
- * @example
- * ```typescript
- * deallocate(ptr, 1024) // Deallocate 1KB
- * ```
- */
-export declare function deallocate(ptr: number, size: number): void;
-/**
- * Reads string data from WebAssembly memory and returns it as UTF-8 bytes.
- *
- * This function provides a safe interface for reading string data from
- * WASM memory, with proper error handling and fallback behavior.
- *
- * @param ptr - Memory pointer to read from
- * @param len - Number of bytes to read
- * @returns UTF-8 encoded bytes of the string data
- *
- * @example
- * ```typescript
- * const data = readBufferSlice(ptr, len)
- * const text = decoder.decode(data) // Convert back to string
- * ```
- */
-export declare function readBufferSlice(ptr: number, len: number): Uint8Array;
-/**
- * Reads a string directly from WebAssembly memory.
- *
- * This is a convenience function that combines memory reading and UTF-8
- * decoding in a single operation.
- *
- * @param ptr - Memory pointer to read from
- * @param len - Number of bytes to read
- * @returns The decoded UTF-8 string
- *
- * @example
- * ```typescript
- * const text = readString(ptr, len)
- * ```
- */
-export declare function readString(ptr: number, len: number): string;
-/**
- * Writes a JavaScript string to WebAssembly memory and returns its location.
- *
- * This function handles the complete process of:
- * 1. Calculating the UTF-8 byte length of the string
- * 2. Allocating sufficient memory in the WASM linear memory
- * 3. Writing the string data to the allocated location
- *
- * @param str - The string to write to memory
- * @returns A tuple containing [pointer, byte_length]
- *
- * @example
- * ```typescript
- * const [ptr, len] = stringToPtr("Hello, World!")
- * // ptr points to the string data, len is the byte length
- * ```
- */
-export declare function stringToPtr(str: string): [number, number];

package/dist/internal/memory.js

@@ -1,152 +0,0 @@
-/**
- * @fileoverview WebAssembly Memory Management Module
- *
- * Provides a high-level interface for managing WebAssembly linear memory operations.
- * This module handles string-based data exchange between JavaScript and the WASM
- * runtime through direct UTF-8 operations, avoiding unnecessary serialization overhead.
- *
- * ## Architecture
- *
- * The memory bridge operates on two main principles:
- * - **Direct String Operations**: Strings are passed directly between JS and WASM
- * - **UTF-8 Encoding**: All string data is handled as UTF-8 encoded bytes
- *
- * ## Usage
- *
- * ```typescript
- * // Allocate memory for a string
- * const [ptr, len] = stringToPtr("Hello, World!")
- *
- * // Read data back from memory
- * const data = readBufferSlice(ptr, len)
- * ```
- */
-// =============================================================================
-// TEXT ENCODING UTILITIES
-// =============================================================================
-/** Reusable TextEncoder instance for UTF-8 string encoding. */
-const encoder = new TextEncoder();
-/** Reusable TextDecoder instance for UTF-8 string decoding. */
-export const decoder = new TextDecoder('utf-8');
-// =============================================================================
-// MEMORY ALLOCATION
-// =============================================================================
-/**
- * Allocates a block of memory within the WebAssembly linear memory space.
- *
- * This function provides the primary interface for requesting memory from
- * the WASM module's allocator. The returned pointer can be used for
- * subsequent read/write operations.
- *
- * @param size - Number of bytes to allocate
- * @returns Memory pointer (offset) to the allocated block
- *
- * @example
- * ```typescript
- * const ptr = allocate(1024) // Allocate 1KB
- * ```
- */
-export function allocate(size) {
-    return __wasm.alloc(size);
-}
-// =============================================================================
-// STRING MEMORY OPERATIONS
-// =============================================================================
-/**
- *
- * @param ptr - Memory pointer to deallocate
- * @param size -  Number of bytes to deallocate
- *
- * @example
- * ```typescript
- * deallocate(ptr, 1024) // Deallocate 1KB
- * ```
- */
-export function deallocate(ptr, size) {
-    __wasm.dealloc(ptr, size);
-}
-/**
- * Reads string data from WebAssembly memory and returns it as UTF-8 bytes.
- *
- * This function provides a safe interface for reading string data from
- * WASM memory, with proper error handling and fallback behavior.
- *
- * @param ptr - Memory pointer to read from
- * @param len - Number of bytes to read
- * @returns UTF-8 encoded bytes of the string data
- *
- * @example
- * ```typescript
- * const data = readBufferSlice(ptr, len)
- * const text = decoder.decode(data) // Convert back to string
- * ```
- */
-export function readBufferSlice(ptr, len) {
-    if (len === 0) {
-        return new Uint8Array(0);
-    }
-    try {
-        const str = __wasm.read_string(ptr, len);
-        return encoder.encode(str);
-    }
-    catch (error) {
-        console.error(`Memory read failed at ptr=${ptr}, len=${len}:`, error);
-        return new Uint8Array(0);
-    }
-}
-// =============================================================================
-// UTILITY FUNCTIONS
-// =============================================================================
-/**
- * Reads a string directly from WebAssembly memory.
- *
- * This is a convenience function that combines memory reading and UTF-8
- * decoding in a single operation.
- *
- * @param ptr - Memory pointer to read from
- * @param len - Number of bytes to read
- * @returns The decoded UTF-8 string
- *
- * @example
- * ```typescript
- * const text = readString(ptr, len)
- * ```
- */
-export function readString(ptr, len) {
-    if (len === 0) {
-        return '';
-    }
-    try {
-        return __wasm.read_string(ptr, len);
-    }
-    catch (error) {
-        console.error(`String read failed at ptr=${ptr}, len=${len}:`, error);
-        return '';
-    }
-}
-/**
- * Writes a JavaScript string to WebAssembly memory and returns its location.
- *
- * This function handles the complete process of:
- * 1. Calculating the UTF-8 byte length of the string
- * 2. Allocating sufficient memory in the WASM linear memory
- * 3. Writing the string data to the allocated location
- *
- * @param str - The string to write to memory
- * @returns A tuple containing [pointer, byte_length]
- *
- * @example
- * ```typescript
- * const [ptr, len] = stringToPtr("Hello, World!")
- * // ptr points to the string data, len is the byte length
- * ```
- */
-export function stringToPtr(str) {
-    if (str.length === 0) {
-        return [allocate(0), 0];
-    }
-    const bytes = encoder.encode(str);
-    const ptr = allocate(bytes.length);
-    __wasm.write_string(ptr, str);
-    return [ptr, bytes.length];
-}