@go-go-golems/os-scripting 0.1.0

package/features/runtimeSessions/runtimeSessionsSlice.js

@@ -0,0 +1,210 @@
+import { createSlice, nanoid } from '@reduxjs/toolkit';
+import { authorizeDomainIntent, authorizeSystemIntent, resolveCapabilityPolicy, } from './capabilityPolicy';
+import { getRuntimeActionDomain, getRuntimeActionKind, getRuntimeActionOperation } from '../../plugin-runtime/contracts';
+const MAX_TIMELINE_ENTRIES = 300;
+const initialState = {
+    sessions: {},
+    timeline: [],
+    pendingDomainIntents: [],
+    pendingSystemIntents: [],
+    pendingNavIntents: [],
+};
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function deepSet(target, path, value) {
+    const keys = path.split('.').filter(Boolean);
+    if (keys.length === 0)
+        return;
+    let current = target;
+    for (let index = 0; index < keys.length - 1; index += 1) {
+        const key = keys[index];
+        const nextValue = current[key];
+        if (!isRecord(nextValue)) {
+            current[key] = {};
+        }
+        current = current[key];
+    }
+    current[keys[keys.length - 1]] = value;
+}
+function clearObject(target) {
+    for (const key of Object.keys(target)) {
+        delete target[key];
+    }
+}
+function applyLocalStateAction(target, operation, payload) {
+    if (operation === 'patch') {
+        if (!isRecord(payload)) {
+            return { outcome: 'ignored', reason: 'patch_requires_object_payload' };
+        }
+        Object.assign(target, payload);
+        return { outcome: 'applied', reason: null };
+    }
+    if (operation === 'set') {
+        if (!isRecord(payload) || typeof payload.path !== 'string') {
+            return { outcome: 'ignored', reason: 'set_requires_{path,value}_payload' };
+        }
+        deepSet(target, payload.path, payload.value);
+        return { outcome: 'applied', reason: null };
+    }
+    if (operation === 'reset') {
+        clearObject(target);
+        return { outcome: 'applied', reason: null };
+    }
+    return { outcome: 'ignored', reason: `unsupported_local_action:${operation}` };
+}
+function appendTimeline(state, payload, kind, outcome, reason) {
+    state.timeline.push({
+        id: payload.id,
+        timestamp: payload.timestamp,
+        sessionId: payload.sessionId,
+        surfaceId: payload.surfaceId,
+        kind,
+        actionType: payload.action.type,
+        payload: payload.action.payload,
+        outcome,
+        reason,
+    });
+    if (state.timeline.length > MAX_TIMELINE_ENTRIES) {
+        state.timeline.splice(0, state.timeline.length - MAX_TIMELINE_ENTRIES);
+    }
+}
+const runtimeSessionsSlice = createSlice({
+    name: 'runtimeSessions',
+    initialState,
+    reducers: {
+        registerRuntimeSession(state, action) {
+            const payload = action.payload;
+            state.sessions[payload.sessionId] = {
+                bundleId: payload.bundleId,
+                status: payload.status ?? 'loading',
+                error: null,
+                sessionState: payload.initialSessionState ? { ...payload.initialSessionState } : {},
+                surfaceState: payload.initialSurfaceState ? { ...payload.initialSurfaceState } : {},
+                capabilities: resolveCapabilityPolicy(payload.capabilities),
+            };
+        },
+        removeRuntimeSession(state, action) {
+            const { sessionId } = action.payload;
+            delete state.sessions[sessionId];
+            state.pendingDomainIntents = state.pendingDomainIntents.filter((intent) => intent.sessionId !== sessionId);
+            state.pendingSystemIntents = state.pendingSystemIntents.filter((intent) => intent.sessionId !== sessionId);
+            state.pendingNavIntents = state.pendingNavIntents.filter((intent) => intent.sessionId !== sessionId);
+        },
+        setRuntimeSessionStatus(state, action) {
+            const session = state.sessions[action.payload.sessionId];
+            if (!session) {
+                return;
+            }
+            session.status = action.payload.status;
+            session.error = action.payload.error ?? null;
+        },
+        ingestRuntimeAction: {
+            reducer(state, action) {
+                const payload = action.payload;
+                const session = state.sessions[payload.sessionId];
+                if (!session) {
+                    appendTimeline(state, payload, 'unknown', 'denied', `missing_session:${payload.sessionId}`);
+                    return;
+                }
+                const kind = getRuntimeActionKind(payload.action.type);
+                if (kind === 'draft') {
+                    if (!session.surfaceState[payload.surfaceId]) {
+                        session.surfaceState[payload.surfaceId] = {};
+                    }
+                    const result = applyLocalStateAction(session.surfaceState[payload.surfaceId], getRuntimeActionOperation(payload.action.type), payload.action.payload);
+                    appendTimeline(state, payload, kind, result.outcome, result.reason);
+                    return;
+                }
+                if (kind === 'filters') {
+                    const result = applyLocalStateAction(session.sessionState, getRuntimeActionOperation(payload.action.type), payload.action.payload);
+                    appendTimeline(state, payload, kind, result.outcome, result.reason);
+                    return;
+                }
+                if (kind === 'domain') {
+                    const domain = getRuntimeActionDomain(payload.action.type);
+                    if (!domain) {
+                        appendTimeline(state, payload, kind, 'ignored', `missing_domain_prefix:${payload.action.type}`);
+                        return;
+                    }
+                    const decision = authorizeDomainIntent(session.capabilities, domain);
+                    if (!decision.allowed) {
+                        appendTimeline(state, payload, kind, 'denied', decision.reason);
+                        return;
+                    }
+                    state.pendingDomainIntents.push({
+                        id: payload.id,
+                        timestamp: payload.timestamp,
+                        sessionId: payload.sessionId,
+                        surfaceId: payload.surfaceId,
+                        domain,
+                        type: payload.action.type,
+                        payload: payload.action.payload,
+                    });
+                    appendTimeline(state, payload, kind, 'applied', null);
+                    return;
+                }
+                if (kind === 'system') {
+                    const decision = authorizeSystemIntent(session.capabilities, payload.action.type);
+                    if (!decision.allowed) {
+                        appendTimeline(state, payload, kind, 'denied', decision.reason);
+                        return;
+                    }
+                    const queued = {
+                        id: payload.id,
+                        timestamp: payload.timestamp,
+                        sessionId: payload.sessionId,
+                        surfaceId: payload.surfaceId,
+                        type: payload.action.type,
+                        payload: payload.action.payload,
+                    };
+                    state.pendingSystemIntents.push(queued);
+                    if (payload.action.type.startsWith('nav.')) {
+                        state.pendingNavIntents.push(queued);
+                    }
+                    appendTimeline(state, payload, kind, 'applied', null);
+                    return;
+                }
+                appendTimeline(state, payload, kind, 'ignored', `unsupported_action_type:${payload.action.type}`);
+            },
+            prepare(payload) {
+                return {
+                    payload: {
+                        ...payload,
+                        id: nanoid(),
+                        timestamp: payload.timestamp ?? new Date().toISOString(),
+                    },
+                };
+            },
+        },
+        dequeuePendingDomainIntent(state, action) {
+            const id = action.payload?.id;
+            if (!id) {
+                state.pendingDomainIntents.shift();
+                return;
+            }
+            state.pendingDomainIntents = state.pendingDomainIntents.filter((intent) => intent.id !== id);
+        },
+        dequeuePendingSystemIntent(state, action) {
+            const id = action.payload?.id;
+            if (!id) {
+                state.pendingSystemIntents.shift();
+                return;
+            }
+            state.pendingSystemIntents = state.pendingSystemIntents.filter((intent) => intent.id !== id);
+        },
+        dequeuePendingNavIntent(state, action) {
+            const id = action.payload?.id;
+            if (!id) {
+                state.pendingNavIntents.shift();
+                return;
+            }
+            state.pendingNavIntents = state.pendingNavIntents.filter((intent) => intent.id !== id);
+        },
+        clearRuntimeTimeline(state) {
+            state.timeline = [];
+        },
+    },
+});
+export const { clearRuntimeTimeline, dequeuePendingDomainIntent, dequeuePendingNavIntent, dequeuePendingSystemIntent, ingestRuntimeAction, registerRuntimeSession, removeRuntimeSession, setRuntimeSessionStatus, } = runtimeSessionsSlice.actions;
+export const runtimeSessionsReducer = runtimeSessionsSlice.reducer;

package/features/runtimeSessions/selectors.d.ts

@@ -0,0 +1,16 @@
+import type { CapabilitySet } from './capabilityPolicy';
+import type { RuntimeSessionsState, RuntimeSessionsStateSlice, RuntimeSessionRecord } from './runtimeSessionsSlice';
+export declare const selectRuntimeSessionsState: (state: RuntimeSessionsStateSlice) => RuntimeSessionsState;
+export declare const selectRuntimeSession: (state: RuntimeSessionsStateSlice, sessionId: string) => RuntimeSessionRecord | undefined;
+export declare const selectRuntimeSessionState: (state: RuntimeSessionsStateSlice, sessionId: string) => Record<string, unknown>;
+export declare const selectRuntimeSurfaceState: (state: RuntimeSessionsStateSlice, sessionId: string, surfaceId: string) => Record<string, unknown>;
+export declare const selectRuntimeTimeline: (state: RuntimeSessionsStateSlice) => import("./runtimeSessionsSlice").RuntimeTimelineEntry[];
+export declare const selectPendingDomainIntents: (state: RuntimeSessionsStateSlice) => import("./runtimeSessionsSlice").DomainIntentEnvelope[];
+export declare const selectPendingSystemIntents: (state: RuntimeSessionsStateSlice) => import("./runtimeSessionsSlice").SystemIntentEnvelope[];
+export declare const selectPendingNavIntents: (state: RuntimeSessionsStateSlice) => import("./runtimeSessionsSlice").SystemIntentEnvelope[];
+/**
+ * Returns the app slices that the runtime host currently projects into VM-facing state.
+ * The result is intended to be consumed with `useSelector(..., shallowEqual)` so callers
+ * rerender only when relevant slice references change.
+ */
+export declare const selectProjectedRuntimeDomains: (state: unknown, allowedSlices?: CapabilitySet) => Record<string, unknown>;

package/features/runtimeSessions/selectors.js

@@ -0,0 +1,40 @@
+const EMPTY_RUNTIME_OBJECT = Object.freeze({});
+const projectedDomainsCache = new WeakMap();
+const ALL_PROJECTED_DOMAINS_CACHE_KEY = '__all__';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export const selectRuntimeSessionsState = (state) => state.runtimeSessions;
+export const selectRuntimeSession = (state, sessionId) => state.runtimeSessions.sessions[sessionId];
+export const selectRuntimeSessionState = (state, sessionId) => state.runtimeSessions.sessions[sessionId]?.sessionState ?? EMPTY_RUNTIME_OBJECT;
+export const selectRuntimeSurfaceState = (state, sessionId, surfaceId) => state.runtimeSessions.sessions[sessionId]?.surfaceState[surfaceId] ?? EMPTY_RUNTIME_OBJECT;
+export const selectRuntimeTimeline = (state) => state.runtimeSessions.timeline;
+export const selectPendingDomainIntents = (state) => state.runtimeSessions.pendingDomainIntents;
+export const selectPendingSystemIntents = (state) => state.runtimeSessions.pendingSystemIntents;
+export const selectPendingNavIntents = (state) => state.runtimeSessions.pendingNavIntents;
+/**
+ * Returns the app slices that the runtime host currently projects into VM-facing state.
+ * The result is intended to be consumed with `useSelector(..., shallowEqual)` so callers
+ * rerender only when relevant slice references change.
+ */
+export const selectProjectedRuntimeDomains = (state, allowedSlices = []) => {
+    if (!isRecord(state)) {
+        return EMPTY_RUNTIME_OBJECT;
+    }
+    if (Array.isArray(allowedSlices) && allowedSlices.length === 0) {
+        return EMPTY_RUNTIME_OBJECT;
+    }
+    const cacheKey = allowedSlices === 'all' ? ALL_PROJECTED_DOMAINS_CACHE_KEY : allowedSlices.join('\u0000');
+    const cachedByState = projectedDomainsCache.get(state);
+    const cached = cachedByState?.get(cacheKey);
+    if (cached) {
+        return cached;
+    }
+    const projected = Object.fromEntries((allowedSlices === 'all' ? Object.keys(state) : allowedSlices)
+        .filter((key) => isRecord(state[key]))
+        .map((key) => [key, state[key]]));
+    const nextCache = cachedByState ?? new Map();
+    nextCache.set(cacheKey, projected);
+    projectedDomainsCache.set(state, nextCache);
+    return projected;
+};

package/hypercard/artifacts/artifactProjectionMiddleware.d.ts

@@ -0,0 +1 @@
+export declare function createArtifactProjectionMiddleware(): import("@reduxjs/toolkit").ListenerMiddlewareInstance<unknown, import("@reduxjs/toolkit").ThunkDispatch<unknown, unknown, import("@reduxjs/toolkit").UnknownAction>, unknown>;

package/hypercard/artifacts/artifactProjectionMiddleware.js

@@ -0,0 +1,66 @@
+import { createListenerMiddleware } from '@reduxjs/toolkit';
+import { timelineSlice } from '@go-go-golems/os-chat';
+import { registerRuntimeSurface } from '../../plugin-runtime';
+import { extractArtifactUpsertFromTimelineEntity } from './artifactRuntime';
+import { upsertArtifact } from './artifactsSlice';
+function runtimeSurfaceEntityIsFinal(entity) {
+    const rawStatus = entity.props && typeof entity.props === 'object'
+        ? entity.props.status
+        : undefined;
+    if (typeof rawStatus !== 'string') {
+        return true;
+    }
+    const status = rawStatus.trim().toLowerCase();
+    return status !== 'streaming' && status !== 'pending';
+}
+function projectArtifactFromEntity(dispatch, entity) {
+    if (!entity) {
+        return;
+    }
+    const upsert = extractArtifactUpsertFromTimelineEntity(entity.kind, entity.props);
+    if (!upsert) {
+        return;
+    }
+    const queueForInjection = runtimeSurfaceEntityIsFinal(entity) &&
+        Boolean(upsert.runtimeSurfaceId && upsert.runtimeSurfaceCode && upsert.packId);
+    dispatch(upsertArtifact({
+        ...upsert,
+        updatedAt: Date.now(),
+        queueForInjection,
+    }));
+    if (queueForInjection && upsert.runtimeSurfaceId && upsert.runtimeSurfaceCode && upsert.packId) {
+        registerRuntimeSurface(upsert.runtimeSurfaceId, upsert.runtimeSurfaceCode, upsert.packId);
+    }
+}
+export function createArtifactProjectionMiddleware() {
+    const listener = createListenerMiddleware();
+    listener.startListening({
+        actionCreator: timelineSlice.actions.addEntity,
+        effect: (action, api) => {
+            projectArtifactFromEntity(api.dispatch, action.payload.entity);
+        },
+    });
+    listener.startListening({
+        actionCreator: timelineSlice.actions.upsertEntity,
+        effect: (action, api) => {
+            projectArtifactFromEntity(api.dispatch, action.payload.entity);
+        },
+    });
+    listener.startListening({
+        actionCreator: timelineSlice.actions.applySnapshot,
+        effect: (action, api) => {
+            for (const entity of action.payload.entities) {
+                projectArtifactFromEntity(api.dispatch, entity);
+            }
+        },
+    });
+    listener.startListening({
+        actionCreator: timelineSlice.actions.mergeSnapshot,
+        effect: (action, api) => {
+            for (const entity of action.payload.entities) {
+                projectArtifactFromEntity(api.dispatch, entity);
+            }
+        },
+    });
+    return listener;
+}

package/hypercard/artifacts/artifactRuntime.d.ts

@@ -0,0 +1,22 @@
+import type { OpenWindowPayload } from '@go-go-golems/os-core/desktop-core';
+import type { ArtifactSource } from './artifactsSlice';
+export interface ArtifactUpsert {
+    id: string;
+    title?: string;
+    template?: string;
+    data?: Record<string, unknown>;
+    source: ArtifactSource;
+    runtimeSurfaceId?: string;
+    runtimeSurfaceCode?: string;
+    packId?: string;
+}
+export declare function normalizeArtifactId(raw: unknown): string | undefined;
+export declare function extractArtifactUpsertFromSem(type: string | undefined, data: Record<string, unknown>): ArtifactUpsert | undefined;
+export declare function extractArtifactUpsertFromTimelineEntity(entityKind: string | undefined, props: unknown): ArtifactUpsert | undefined;
+export declare function buildArtifactOpenWindowPayload(input: {
+    artifactId: string;
+    template?: string;
+    title?: string;
+    bundleId?: string;
+    runtimeSurfaceId?: string;
+}): OpenWindowPayload | undefined;

package/hypercard/artifacts/artifactRuntime.js

@@ -0,0 +1,137 @@
+import { recordField, stringField, structuredRecordFromUnknown } from '@go-go-golems/os-chat';
+export function normalizeArtifactId(raw) {
+    if (typeof raw !== 'string') {
+        return undefined;
+    }
+    let value = raw.trim();
+    if (!value) {
+        return undefined;
+    }
+    for (let i = 0; i < 2; i += 1) {
+        const isDoubleQuoted = value.startsWith('"') && value.endsWith('"');
+        const isSingleQuoted = value.startsWith("'") && value.endsWith("'");
+        if (value.length > 1 && (isDoubleQuoted || isSingleQuoted)) {
+            value = value.slice(1, -1).trim();
+            continue;
+        }
+        break;
+    }
+    return value || undefined;
+}
+function artifactFromStructured(record) {
+    const payload = recordField(record, 'data');
+    const artifact = payload ? recordField(payload, 'artifact') : undefined;
+    const artifactId = normalizeArtifactId(artifact ? stringField(artifact, 'id') : undefined);
+    if (!artifactId) {
+        return undefined;
+    }
+    return {
+        id: artifactId,
+        title: stringField(record, 'title'),
+        data: artifact ? recordField(artifact, 'data') : undefined,
+        source: 'card',
+    };
+}
+function cardFieldsFromStructured(record) {
+    const payload = recordField(record, 'data');
+    const card = payload ? recordField(payload, 'card') : undefined;
+    const runtime = payload ? recordField(payload, 'runtime') : undefined;
+    if (!card) {
+        return {
+            packId: runtime ? stringField(runtime, 'pack') : undefined,
+        };
+    }
+    return {
+        runtimeSurfaceId: stringField(card, 'id'),
+        runtimeSurfaceCode: stringField(card, 'code'),
+        packId: runtime ? stringField(runtime, 'pack') : undefined,
+    };
+}
+function artifactFromCardResult(resultRecord) {
+    const upsert = artifactFromStructured(resultRecord);
+    if (!upsert) {
+        return undefined;
+    }
+    return {
+        ...upsert,
+        ...cardFieldsFromStructured(resultRecord),
+    };
+}
+function artifactFromTimelineCardProps(props) {
+    const resultRecord = structuredRecordFromUnknown(props.result) ??
+        structuredRecordFromUnknown(props.resultRaw) ??
+        props;
+    return artifactFromCardResult(resultRecord);
+}
+export function extractArtifactUpsertFromSem(type, data) {
+    if (!type) {
+        return undefined;
+    }
+    if (type === 'hypercard.card.v2') {
+        return artifactFromCardResult(data);
+    }
+    if (type !== 'timeline.upsert') {
+        return undefined;
+    }
+    const entity = recordField(data, 'entity');
+    if (!entity) {
+        return undefined;
+    }
+    const entityKind = stringField(entity, 'kind');
+    if (entityKind !== 'hypercard.card.v2') {
+        return undefined;
+    }
+    const props = recordField(entity, 'props');
+    if (!props) {
+        return undefined;
+    }
+    return artifactFromTimelineCardProps(props);
+}
+export function extractArtifactUpsertFromTimelineEntity(entityKind, props) {
+    if (String(entityKind || '') !== 'hypercard.card.v2') {
+        return undefined;
+    }
+    if (!props || typeof props !== 'object' || Array.isArray(props)) {
+        return undefined;
+    }
+    return artifactFromTimelineCardProps(props);
+}
+function sanitizeArtifactKey(value) {
+    return value.trim().toLowerCase().replace(/[^a-z0-9_-]+/g, '-');
+}
+function cleanString(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+export function buildArtifactOpenWindowPayload(input) {
+    const artifactId = normalizeArtifactId(input.artifactId);
+    if (!artifactId) {
+        return undefined;
+    }
+    const runtimeSurfaceId = cleanString(input.runtimeSurfaceId);
+    if (!runtimeSurfaceId) {
+        return undefined;
+    }
+    const safeKey = sanitizeArtifactKey(artifactId);
+    const title = input.title?.trim() || `Artifact ${artifactId}`;
+    const bundleId = cleanString(input.bundleId) ?? 'inventory';
+    return {
+        id: `window:artifact:${safeKey}`,
+        title,
+        icon: '🃏',
+        bounds: { x: 220, y: 50, w: 520, h: 420 },
+        content: {
+            kind: 'surface',
+            surface: {
+                bundleId,
+                surfaceId: runtimeSurfaceId,
+                surfaceSessionId: `artifact-session:${safeKey}`,
+                param: artifactId,
+            },
+        },
+        dedupeKey: `artifact:${artifactId}`,
+    };
+}

package/hypercard/artifacts/artifactsSelectors.d.ts

@@ -0,0 +1,10 @@
+import type { ArtifactRecord } from './artifactsSlice';
+interface ArtifactsStateShape {
+    byId: Record<string, ArtifactRecord>;
+}
+interface ArtifactsStateSlice {
+    hypercardArtifacts: ArtifactsStateShape;
+}
+export declare const selectArtifactsById: (state: ArtifactsStateSlice) => Record<string, ArtifactRecord>;
+export declare const selectArtifactById: (state: ArtifactsStateSlice, artifactId: string) => ArtifactRecord | undefined;
+export {};

package/hypercard/artifacts/artifactsSelectors.js

@@ -0,0 +1,2 @@
+export const selectArtifactsById = (state) => state.hypercardArtifacts.byId;
+export const selectArtifactById = (state, artifactId) => state.hypercardArtifacts.byId[artifactId];

package/hypercard/artifacts/artifactsSlice.d.ts

@@ -0,0 +1,38 @@
+export type ArtifactSource = 'widget' | 'card';
+export interface ArtifactRecord {
+    id: string;
+    title: string;
+    template: string;
+    data: Record<string, unknown>;
+    source: ArtifactSource;
+    updatedAt: number;
+    runtimeSurfaceId?: string;
+    runtimeSurfaceCode?: string;
+    packId?: string;
+    injectionStatus?: 'pending' | 'injected' | 'failed';
+    injectionError?: string;
+}
+export interface ArtifactsState {
+    byId: Record<string, ArtifactRecord>;
+}
+export declare const upsertArtifact: import("@reduxjs/toolkit").ActionCreatorWithPayload<{
+    id: string;
+    title?: string;
+    template?: string;
+    data?: Record<string, unknown>;
+    source: ArtifactSource;
+    updatedAt?: number;
+    runtimeSurfaceId?: string;
+    runtimeSurfaceCode?: string;
+    packId?: string;
+    queueForInjection?: boolean;
+}, "artifacts/upsertArtifact">, markRuntimeSurfaceInjectionResults: import("@reduxjs/toolkit").ActionCreatorWithPayload<{
+    injectedSurfaceIds?: string[];
+    failed?: Array<{
+        surfaceId: string;
+        error?: string;
+    }>;
+    updatedAt?: number;
+}, "artifacts/markRuntimeSurfaceInjectionResults">, clearArtifacts: import("@reduxjs/toolkit").ActionCreatorWithoutPayload<"artifacts/clearArtifacts">;
+export declare const artifactsReducer: import("@reduxjs/toolkit").Reducer<ArtifactsState>;
+export declare const hypercardArtifactsReducer: import("@reduxjs/toolkit").Reducer<ArtifactsState>;

package/hypercard/artifacts/artifactsSlice.js

@@ -0,0 +1,94 @@
+import { createSlice } from '@reduxjs/toolkit';
+const initialState = {
+    byId: {},
+};
+function cleanString(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function cleanObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return {};
+    }
+    return value;
+}
+const artifactsSlice = createSlice({
+    name: 'artifacts',
+    initialState,
+    reducers: {
+        upsertArtifact(state, action) {
+            const id = cleanString(action.payload.id);
+            if (!id) {
+                return;
+            }
+            const existing = state.byId[id];
+            const title = cleanString(action.payload.title) ?? existing?.title ?? id;
+            const template = cleanString(action.payload.template) ?? existing?.template ?? '';
+            const data = action.payload.data !== undefined
+                ? cleanObject(action.payload.data)
+                : existing?.data ?? {};
+            const source = action.payload.source ?? existing?.source ?? 'widget';
+            const updatedAt = action.payload.updatedAt ?? Date.now();
+            const runtimeSurfaceId = cleanString(action.payload.runtimeSurfaceId) ?? existing?.runtimeSurfaceId;
+            const runtimeSurfaceCode = cleanString(action.payload.runtimeSurfaceCode) ?? existing?.runtimeSurfaceCode;
+            const packId = cleanString(action.payload.packId) ?? existing?.packId;
+            const queueForInjection = action.payload.queueForInjection === true;
+            state.byId[id] = {
+                id,
+                title,
+                template,
+                data,
+                source,
+                updatedAt,
+                runtimeSurfaceId,
+                runtimeSurfaceCode,
+                packId,
+                injectionStatus: runtimeSurfaceCode && queueForInjection
+                    ? (existing?.injectionStatus ?? 'pending')
+                    : existing?.injectionStatus,
+                injectionError: existing?.injectionError,
+            };
+        },
+        markRuntimeSurfaceInjectionResults(state, action) {
+            const injected = new Set((action.payload.injectedSurfaceIds ?? [])
+                .map((id) => cleanString(id))
+                .filter((id) => typeof id === 'string'));
+            const failed = new Map();
+            for (const item of action.payload.failed ?? []) {
+                const surfaceId = cleanString(item.surfaceId);
+                if (!surfaceId)
+                    continue;
+                failed.set(surfaceId, cleanString(item.error));
+            }
+            if (injected.size === 0 && failed.size === 0) {
+                return;
+            }
+            const updatedAt = action.payload.updatedAt ?? Date.now();
+            for (const artifact of Object.values(state.byId)) {
+                const runtimeSurfaceId = cleanString(artifact.runtimeSurfaceId);
+                if (!runtimeSurfaceId)
+                    continue;
+                if (injected.has(runtimeSurfaceId)) {
+                    artifact.injectionStatus = 'injected';
+                    artifact.injectionError = undefined;
+                    artifact.updatedAt = updatedAt;
+                    continue;
+                }
+                if (failed.has(runtimeSurfaceId)) {
+                    artifact.injectionStatus = 'failed';
+                    artifact.injectionError = failed.get(runtimeSurfaceId);
+                    artifact.updatedAt = updatedAt;
+                }
+            }
+        },
+        clearArtifacts(state) {
+            state.byId = {};
+        },
+    },
+});
+export const { upsertArtifact, markRuntimeSurfaceInjectionResults, clearArtifacts } = artifactsSlice.actions;
+export const artifactsReducer = artifactsSlice.reducer;
+export const hypercardArtifactsReducer = artifactsSlice.reducer;

package/hypercard/debug/RuntimeSurfaceDebugWindow.d.ts

@@ -0,0 +1,7 @@
+import { type RuntimeBundleDefinition } from '@go-go-golems/os-core';
+export interface RuntimeSurfaceDebugWindowProps {
+    ownerAppId: string;
+    bundles?: RuntimeBundleDefinition[];
+    initialStackId?: string;
+}
+export declare function RuntimeSurfaceDebugWindow({ ownerAppId, bundles, initialStackId, }: RuntimeSurfaceDebugWindowProps): import("react/jsx-runtime").JSX.Element;