@seriousgaming/sdk 0.0.0-stage → 1.0.0-alpha.2

package/lib/build/callbacks.js

@@ -0,0 +1,32 @@
+/**
+ * Callback interfaces for SDK components
+ *
+ * Defines the callbacks available to the engine, user interfaces, and configuration
+ * user interfaces. LLM-specific types are imported from ./llm.
+ *
+ * Asset references — every callback below that takes or returns a file
+ * identifier uses the unified asset URI scheme:
+ *
+ *   `asset:<path>` — package-bundled file. The path is relative to the
+ *                    active scenario's `assets/` directory.
+ *   `blob:<id>`    — runtime-uploaded file. The id is whatever the runtime
+ *                    assigns when the blob was stored.
+ *
+ * Any string starting with `asset:` or `blob:` is unambiguously an asset
+ * reference. No other strings are.
+ */
+/**
+ * Error thrown when a resource invokes a callback it did not declare in its
+ * bundle's `uses` array. Carries the offending resource identifier and the
+ * callback name so a runtime can surface both to the operator.
+ */
+export class UndeclaredApiUseError extends Error {
+    resourceIdentifier;
+    api;
+    constructor(resourceIdentifier, api) {
+        super(`Resource "${resourceIdentifier}" attempted to call callback "${api}" but did not declare it in its bundle's "uses" array. Add "${api}" to the bundle's uses to allow this call.`);
+        this.name = 'UndeclaredApiUseError';
+        this.resourceIdentifier = resourceIdentifier;
+        this.api = api;
+    }
+}

package/lib/build/context-merge.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The §9.5 context deep-merge, as the UI wrappers apply it to their optimistic
+ * local copy. Internal to the SDK: no entry point exports the functions here,
+ * only the `ContextUpdate` and `ContextDeletePath` types.
+ *
+ * The runtime applies the same merge from its own copy in
+ * `@seriousgaming/sdk-tools/runtime`, and
+ * `context-merge.parity.test.ts` there holds the two to one table of cases.
+ * Both must apply identical semantics or a UI sending a minimal patch sees its
+ * local view diverge from the host's until the next snapshot:
+ *
+ * - Plain objects are merged recursively
+ * - Arrays, scalars, `null`, and non-plain objects replace the base value
+ * - `__proto__`, `constructor`, and `prototype` keys are ignored (payloads
+ *   cross an untrusted iframe boundary)
+ *
+ * A deep merge cannot express key deletion, so an update carries deletions
+ * beside the patch rather than inside it (see {@link ContextDeletePath} and
+ * {@link applyContextUpdate}).
+ */
+/**
+ * A partial update accepted by `setData` and merged with `deepMergeContext`.
+ * Mirrors the merge semantics at the type level: object values may be given
+ * partially (they merge), while arrays and scalars must be given whole (they
+ * replace).
+ */
+export type ContextUpdate<T> = {
+    [K in keyof T]?: T[K] extends ReadonlyArray<unknown> ? T[K] : T[K] extends Record<string, unknown> ? ContextUpdate<T[K]> : T[K];
+};
+/**
+ * Where to remove a key, as a path from the root of the context.
+ *
+ * The dotted form reads best and covers almost everything, because the first
+ * two segments are a capability identifier and a variable name. Give the
+ * segments as an array where a key of your own could contain a dot — a
+ * collection keyed by something arbitrary, say — and nothing has to be
+ * escaped.
+ *
+ * ```typescript
+ * 'pinboard.Notes.01H8XY'
+ * ['pinboard', 'Notes', 'a.key.with.dots']
+ * ```
+ */
+export type ContextDeletePath = string | readonly string[];
+export declare function deepMergeContext<T extends Record<string, unknown>>(base: T, patch: Record<string, unknown>): T;
+/**
+ * The parts of `update` that differ from `current`, or undefined when nothing
+ * does. Plain objects are compared key by key; anything else by value.
+ */
+export declare function changedFrom(update: unknown, current: unknown): unknown;
+/**
+ * Apply one context update: merge the patch, then remove the deleted paths.
+ *
+ * Deletions are applied after the merge so a single update can replace an
+ * entry — write the new key, drop the old — without the order of the two
+ * mattering to the caller. Every runtime applying an update MUST use this
+ * order (SPECIFICATION.md §9.5).
+ */
+export declare function applyContextUpdate<T extends Record<string, unknown>>(base: T, patch: Record<string, unknown>, deletes?: readonly ContextDeletePath[]): T;

package/lib/build/context-merge.js

@@ -0,0 +1,118 @@
+/**
+ * The §9.5 context deep-merge, as the UI wrappers apply it to their optimistic
+ * local copy. Internal to the SDK: no entry point exports the functions here,
+ * only the `ContextUpdate` and `ContextDeletePath` types.
+ *
+ * The runtime applies the same merge from its own copy in
+ * `@seriousgaming/sdk-tools/runtime`, and
+ * `context-merge.parity.test.ts` there holds the two to one table of cases.
+ * Both must apply identical semantics or a UI sending a minimal patch sees its
+ * local view diverge from the host's until the next snapshot:
+ *
+ * - Plain objects are merged recursively
+ * - Arrays, scalars, `null`, and non-plain objects replace the base value
+ * - `__proto__`, `constructor`, and `prototype` keys are ignored (payloads
+ *   cross an untrusted iframe boundary)
+ *
+ * A deep merge cannot express key deletion, so an update carries deletions
+ * beside the patch rather than inside it (see {@link ContextDeletePath} and
+ * {@link applyContextUpdate}).
+ */
+const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+/**
+ * Realm-safe plain-object test.
+ *
+ * Logic is evaluated in its own V8 context, so the objects it returns
+ * carry that realm's `Object.prototype`, not this one's. Comparing against the
+ * host's `Object.prototype` alone classifies them as non-plain and replaces
+ * them, blanking sibling fields a partial patch never touched (#394). A plain
+ * object from any realm sits directly on a prototype that is itself rootless,
+ * which `Date`, `Map`, and class instances do not.
+ */
+function isPlainObject(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    if (Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    if (proto === null || proto === Object.prototype)
+        return true;
+    return Object.getPrototypeOf(proto) === null;
+}
+export function deepMergeContext(base, patch) {
+    const result = { ...base };
+    for (const key of Object.keys(patch)) {
+        if (UNSAFE_KEYS.has(key))
+            continue;
+        const baseValue = result[key];
+        const patchValue = patch[key];
+        result[key] =
+            isPlainObject(baseValue) && isPlainObject(patchValue)
+                ? deepMergeContext(baseValue, patchValue)
+                : patchValue;
+    }
+    return result;
+}
+/**
+ * The parts of `update` that differ from `current`, or undefined when nothing
+ * does. Plain objects are compared key by key; anything else by value.
+ */
+export function changedFrom(update, current) {
+    if (isPlainObject(update) && isPlainObject(current)) {
+        const changed = {};
+        for (const [key, value] of Object.entries(update)) {
+            if (UNSAFE_KEYS.has(key))
+                continue;
+            const difference = changedFrom(value, current[key]);
+            if (difference !== undefined)
+                changed[key] = difference;
+        }
+        return Object.keys(changed).length > 0 ? changed : undefined;
+    }
+    return JSON.stringify(update) === JSON.stringify(current) ? undefined : update;
+}
+function segmentsOf(path) {
+    return typeof path === 'string' ? path.split('.') : [...path];
+}
+/**
+ * Remove one path from a context, cloning only the objects along the way.
+ *
+ * A path that does not resolve is not an error: two participants clearing the
+ * same note both send the delete, and the second arriving to find it already
+ * gone is the system working.
+ */
+function deletePath(base, path) {
+    const segments = segmentsOf(path);
+    if (segments.length === 0 || segments.some((segment) => UNSAFE_KEYS.has(segment))) {
+        return base;
+    }
+    const [head, ...rest] = segments;
+    if (!Object.prototype.hasOwnProperty.call(base, head))
+        return base;
+    if (rest.length === 0) {
+        const result = { ...base };
+        delete result[head];
+        return result;
+    }
+    const child = base[head];
+    if (!isPlainObject(child))
+        return base;
+    const prunedChild = deletePath(child, rest);
+    if (prunedChild === child)
+        return base;
+    return { ...base, [head]: prunedChild };
+}
+/**
+ * Apply one context update: merge the patch, then remove the deleted paths.
+ *
+ * Deletions are applied after the merge so a single update can replace an
+ * entry — write the new key, drop the old — without the order of the two
+ * mattering to the caller. Every runtime applying an update MUST use this
+ * order (SPECIFICATION.md §9.5).
+ */
+export function applyContextUpdate(base, patch, deletes) {
+    const merged = deepMergeContext(base, patch);
+    if (!deletes || deletes.length === 0)
+        return merged;
+    return deletes.reduce((context, path) => deletePath(context, path), merged);
+}

package/lib/build/document.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Document Extraction Types
+ *
+ * Provides types for extracting text content from documents (PDF, etc.)
+ * through the Serious Gaming SDK. The extracted text is suitable for
+ * passing to an LLM for further processing.
+ */
+/**
+ * Response from extracting text from a document
+ */
+export interface ExtractTextResponse {
+    /**
+     * The extracted text content, typically plain text or markdown
+     */
+    content: string;
+    /**
+     * MIME type of the source document (e.g. 'application/pdf')
+     */
+    mimeType: string;
+}
+/**
+ * Function for extracting text from a document referenced under the unified
+ * asset URI scheme.
+ *
+ * The argument is an asset reference: either `asset:<path>` for a package-
+ * bundled file resolved against the active scenario's `assets/` directory,
+ * or `blob:<id>` for a runtime-uploaded file. The underlying parsing
+ * strategy is determined by the platform.
+ *
+ * Example:
+ * ```typescript
+ * const fromUpload = await callbacks.extractText("blob:abc123");
+ * const fromAssets = await callbacks.extractText("asset:briefing.pdf");
+ * ```
+ */
+export type ExtractTextFunction = (reference: string) => Promise<ExtractTextResponse>;

package/lib/build/document.js

@@ -0,0 +1,8 @@
+/**
+ * Document Extraction Types
+ *
+ * Provides types for extracting text content from documents (PDF, etc.)
+ * through the Serious Gaming SDK. The extracted text is suitable for
+ * passing to an LLM for further processing.
+ */
+export {};

package/lib/build/encoding.d.ts

@@ -0,0 +1,26 @@
+/**
+ * UTF-8 encoding helpers for author logic.
+ *
+ * The production runtime is a bare V8 isolate that exposes only the ECMAScript
+ * intrinsics — `TextEncoder`, `TextDecoder`, `Buffer`, `atob`, and `btoa` do
+ * not exist there (SPECIFICATION.md §3.2). These helpers implement UTF-8
+ * conversion in plain ECMAScript so the engine can produce bytes for `writeBlob`
+ * or read bytes from `readAsset` / `extractText` identically in the dev server
+ * and in production, with no host global. They are compiled into the author's
+ * bundle, so there is nothing for a runtime to provide.
+ *
+ * Both handle the full Unicode range, including astral-plane code points
+ * represented as surrogate pairs.
+ */
+/**
+ * Encode a string to its UTF-8 byte sequence.
+ *
+ * A portable replacement for `new TextEncoder().encode(input)`.
+ */
+export declare function encodeUtf8(input: string): Uint8Array;
+/**
+ * Decode a UTF-8 byte sequence to a string.
+ *
+ * A portable replacement for `new TextDecoder().decode(bytes)`.
+ */
+export declare function decodeUtf8(bytes: Uint8Array): string;

package/lib/build/encoding.js

@@ -0,0 +1,78 @@
+/**
+ * UTF-8 encoding helpers for author logic.
+ *
+ * The production runtime is a bare V8 isolate that exposes only the ECMAScript
+ * intrinsics — `TextEncoder`, `TextDecoder`, `Buffer`, `atob`, and `btoa` do
+ * not exist there (SPECIFICATION.md §3.2). These helpers implement UTF-8
+ * conversion in plain ECMAScript so the engine can produce bytes for `writeBlob`
+ * or read bytes from `readAsset` / `extractText` identically in the dev server
+ * and in production, with no host global. They are compiled into the author's
+ * bundle, so there is nothing for a runtime to provide.
+ *
+ * Both handle the full Unicode range, including astral-plane code points
+ * represented as surrogate pairs.
+ */
+/**
+ * Encode a string to its UTF-8 byte sequence.
+ *
+ * A portable replacement for `new TextEncoder().encode(input)`.
+ */
+export function encodeUtf8(input) {
+    const bytes = [];
+    // Iterating a string with for…of yields whole code points, so surrogate
+    // pairs are already combined.
+    for (const character of input) {
+        const codePoint = character.codePointAt(0) ?? 0;
+        if (codePoint < 0x80) {
+            bytes.push(codePoint);
+        }
+        else if (codePoint < 0x800) {
+            bytes.push(0xc0 | (codePoint >> 6), 0x80 | (codePoint & 0x3f));
+        }
+        else if (codePoint < 0x10000) {
+            bytes.push(0xe0 | (codePoint >> 12), 0x80 | ((codePoint >> 6) & 0x3f), 0x80 | (codePoint & 0x3f));
+        }
+        else {
+            bytes.push(0xf0 | (codePoint >> 18), 0x80 | ((codePoint >> 12) & 0x3f), 0x80 | ((codePoint >> 6) & 0x3f), 0x80 | (codePoint & 0x3f));
+        }
+    }
+    return Uint8Array.from(bytes);
+}
+/**
+ * Decode a UTF-8 byte sequence to a string.
+ *
+ * A portable replacement for `new TextDecoder().decode(bytes)`.
+ */
+export function decodeUtf8(bytes) {
+    let result = '';
+    let index = 0;
+    const length = bytes.length;
+    while (index < length) {
+        const byte1 = bytes[index++] ?? 0;
+        let codePoint;
+        if (byte1 < 0x80) {
+            codePoint = byte1;
+        }
+        else if ((byte1 & 0xe0) === 0xc0) {
+            const byte2 = bytes[index++] ?? 0;
+            codePoint = ((byte1 & 0x1f) << 6) | (byte2 & 0x3f);
+        }
+        else if ((byte1 & 0xf0) === 0xe0) {
+            const byte2 = bytes[index++] ?? 0;
+            const byte3 = bytes[index++] ?? 0;
+            codePoint = ((byte1 & 0x0f) << 12) | ((byte2 & 0x3f) << 6) | (byte3 & 0x3f);
+        }
+        else {
+            const byte2 = bytes[index++] ?? 0;
+            const byte3 = bytes[index++] ?? 0;
+            const byte4 = bytes[index++] ?? 0;
+            codePoint =
+                ((byte1 & 0x07) << 18) |
+                    ((byte2 & 0x3f) << 12) |
+                    ((byte3 & 0x3f) << 6) |
+                    (byte4 & 0x3f);
+        }
+        result += String.fromCodePoint(codePoint);
+    }
+    return result;
+}