@go-go-golems/os-scripting 0.1.0

package/hypercard/debug/RuntimeSurfaceDebugWindow.js

@@ -0,0 +1,181 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useState } from 'react';
+import { useSelector } from 'react-redux';
+import { useDispatch } from 'react-redux';
+import { openWindow } from '@go-go-golems/os-core/desktop-core';
+import { getPendingRuntimeSurfaces, onRegistryChange, } from '../../plugin-runtime';
+import { SyntaxHighlight } from '@go-go-golems/os-chat';
+import { openCodeEditor } from '../editor/editorLaunch';
+import { useRegisteredRuntimeDebugStacks } from './runtimeDebugRegistry';
+import { useRegisteredJsSessionDebugSources } from './jsSessionDebugRegistry';
+import { buildTaskManagerWindowPayload } from '../task-manager/taskManagerApp';
+function nextDebugSessionId(prefix) {
+    if (typeof globalThis.crypto?.randomUUID === 'function') {
+        return `${prefix}${globalThis.crypto.randomUUID()}`;
+    }
+    return `${prefix}${Date.now()}`;
+}
+function buildBundleSurfaceWindowPayload(bundle, surfaceId) {
+    const surface = bundle.surfaces[surfaceId];
+    if (!surface) {
+        return null;
+    }
+    const sessionId = nextDebugSessionId(`runtime-debug:${bundle.id}:${surfaceId}:`);
+    return {
+        id: `window:runtime-debug:${bundle.id}:${surfaceId}:${sessionId}`,
+        title: surface.title ?? surfaceId,
+        icon: surface.icon ?? '📄',
+        bounds: { x: 180, y: 56, w: 960, h: 700 },
+        content: {
+            kind: 'surface',
+            surface: {
+                bundleId: bundle.id,
+                surfaceId,
+                surfaceSessionId: sessionId,
+            },
+        },
+    };
+}
+function surfaceSource(surface) {
+    const runtime = surface.meta?.runtime;
+    if (!runtime || typeof runtime !== 'object') {
+        return null;
+    }
+    const source = runtime.source;
+    return typeof source === 'string' && source.trim().length > 0 ? source : null;
+}
+function Section({ title, children }) {
+    return (_jsxs("div", { style: { marginBottom: 16 }, children: [_jsx("div", { style: { fontWeight: 700, fontSize: 13, borderBottom: '1px solid #999', paddingBottom: 4, marginBottom: 8, color: '#111' }, children: title }), children] }));
+}
+function CodePreview({ code, maxLines = 8 }) {
+    return _jsx(SyntaxHighlight, { code: code, language: "javascript", maxLines: maxLines });
+}
+function Badge({ text, color }) {
+    return (_jsx("span", { style: {
+            display: 'inline-block',
+            fontSize: 10,
+            fontWeight: 600,
+            padding: '1px 6px',
+            borderRadius: 3,
+            background: color,
+            color: '#fff',
+            marginLeft: 6,
+        }, children: text }));
+}
+export function RuntimeSurfaceDebugWindow({ ownerAppId, bundles, initialStackId, }) {
+    const dispatch = useDispatch();
+    const [registryCards, setRegistryCards] = useState(getPendingRuntimeSurfaces());
+    const registeredStacks = useRegisteredRuntimeDebugStacks();
+    const jsSessionSources = useRegisteredJsSessionDebugSources();
+    const availableBundles = useMemo(() => (bundles && bundles.length > 0 ? [...bundles] : registeredStacks), [bundles, registeredStacks]);
+    const [jsSessions, setJsSessions] = useState([]);
+    const [selectedStackId, setSelectedStackId] = useState(initialStackId ?? availableBundles[0]?.id ?? null);
+    useEffect(() => {
+        const update = () => setRegistryCards(getPendingRuntimeSurfaces());
+        return onRegistryChange(update);
+    }, []);
+    useEffect(() => {
+        const candidateId = (selectedStackId && availableBundles.some((bundle) => bundle.id === selectedStackId))
+            ? selectedStackId
+            : initialStackId ?? availableBundles[0]?.id ?? null;
+        if (candidateId !== selectedStackId) {
+            setSelectedStackId(candidateId);
+        }
+    }, [availableBundles, initialStackId, selectedStackId]);
+    useEffect(() => {
+        const update = () => {
+            setJsSessions(jsSessionSources.flatMap((source) => source.broker.listSessions().map((session) => ({
+                ...session,
+                sourceId: source.id,
+                sourceTitle: source.title,
+            }))));
+        };
+        update();
+        const unsubscribes = jsSessionSources.map((source) => source.broker.subscribe(update));
+        return () => {
+            unsubscribes.forEach((unsubscribe) => unsubscribe());
+        };
+    }, [jsSessionSources]);
+    const artifacts = useSelector((s) => s.hypercardArtifacts?.byId ?? {});
+    const sessions = useSelector((s) => s.runtimeSessions?.sessions ?? {});
+    const windowingSessions = useSelector((s) => s.windowing?.sessions ?? {});
+    const bundlesById = useMemo(() => new Map(availableBundles.map((bundle) => [bundle.id, bundle])), [availableBundles]);
+    const activeBundle = availableBundles.find((bundle) => bundle.id === selectedStackId) ?? availableBundles[0];
+    const bundleSurfaces = activeBundle ? Object.values(activeBundle.surfaces) : [];
+    const runtimeArtifacts = Object.values(artifacts).filter((artifact) => artifact.runtimeSurfaceId);
+    const td = { padding: '3px 8px', fontSize: 11, borderBottom: '1px solid #ccc', verticalAlign: 'top', color: '#111' };
+    const th = { ...td, fontWeight: 700, background: '#e8e8f0', position: 'sticky', top: 0, color: '#111' };
+    const launchBundleSurface = (bundleId, surfaceId) => {
+        const bundle = bundlesById.get(bundleId);
+        if (!bundle) {
+            return;
+        }
+        const payload = buildBundleSurfaceWindowPayload(bundle, surfaceId);
+        if (!payload) {
+            return;
+        }
+        dispatch(openWindow(payload));
+    };
+    const sessionCurrentSurfaceIds = useMemo(() => {
+        const entries = Object.entries(sessions).map(([sessionId, session]) => {
+            const nav = windowingSessions[sessionId]?.nav;
+            const navSurface = Array.isArray(nav) && nav.length > 0 && typeof nav[nav.length - 1]?.surface === 'string'
+                ? nav[nav.length - 1]?.surface ?? null
+                : null;
+            const fallbackSurface = Object.keys(session.surfaceState ?? {})[0] ?? null;
+            return [sessionId, navSurface ?? fallbackSurface];
+        });
+        return new Map(entries);
+    }, [sessions, windowingSessions]);
+    return (_jsxs("div", { style: { padding: 12, fontFamily: 'monospace', fontSize: 12, color: '#111', overflow: 'auto', height: '100%' }, children: [_jsxs(Section, { title: activeBundle ? `📦 Bundle: ${activeBundle.name} (${activeBundle.id})` : '📦 Bundle: (none provided)', children: [availableBundles.length > 1 && (_jsxs("label", { style: { display: 'grid', gap: 4, marginBottom: 8, fontSize: 11 }, children: [_jsx("span", { style: { color: '#555' }, children: "Selected bundle" }), _jsx("select", { value: activeBundle?.id ?? '', onChange: (event) => setSelectedStackId(event.target.value), style: { width: 260, padding: '4px 6px', fontFamily: 'inherit', fontSize: 12 }, children: availableBundles.map((bundle) => (_jsxs("option", { value: bundle.id, children: [bundle.name, " (", bundle.id, ")"] }, bundle.id))) })] })), _jsxs("div", { style: { fontSize: 11, color: '#555', marginBottom: 6 }, children: ["homeSurface: ", _jsx("code", { children: activeBundle?.homeSurface ?? '—' }), " \u00B7 ", bundleSurfaces.length, " predefined surfaces"] }), _jsxs("table", { style: { width: '100%', borderCollapse: 'collapse' }, children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { style: th, children: "Icon" }), _jsx("th", { style: th, children: "ID" }), _jsx("th", { style: th, children: "Title" }), _jsx("th", { style: th, children: "Type" }), _jsx("th", { style: th, children: "Actions" })] }) }), _jsx("tbody", { children: bundleSurfaces.map(c => (_jsxs("tr", { children: [_jsx("td", { style: td, children: c.icon }), _jsx("td", { style: td, children: _jsx("code", { children: c.id }) }), _jsx("td", { style: td, children: c.title }), _jsx("td", { style: td, children: c.type }), _jsx("td", { style: td, children: _jsxs("div", { style: { display: 'flex', gap: 6, flexWrap: 'wrap' }, children: [_jsx("button", { onClick: () => activeBundle && launchBundleSurface(activeBundle.id, c.id), style: {
+                                                            fontSize: 10,
+                                                            padding: '1px 6px',
+                                                            borderRadius: 3,
+                                                            border: '1px solid #999',
+                                                            background: '#f0f0f0',
+                                                            cursor: 'pointer',
+                                                        }, children: "\u25B6 Open" }), surfaceSource(c) ? (_jsx("button", { onClick: () => openCodeEditor(dispatch, { ownerAppId, surfaceId: c.id }, surfaceSource(c) ?? ''), style: {
+                                                            fontSize: 10,
+                                                            padding: '1px 6px',
+                                                            borderRadius: 3,
+                                                            border: '1px solid #999',
+                                                            background: '#f0f0f0',
+                                                            cursor: 'pointer',
+                                                        }, children: "\u270F\uFE0F Edit" })) : null] }) })] }, c.id))) })] })] }), _jsxs(Section, { title: `🃏 Runtime Surface Registry (${registryCards.length})`, children: [_jsx("div", { style: { fontSize: 11, color: '#555', marginBottom: 8 }, children: "Injected runtime surfaces from artifacts and ad-hoc registration appear here. Built-in bundle surfaces are listed above." }), registryCards.length === 0 ? (_jsx("div", { style: { fontSize: 11, color: '#555' }, children: "No runtime surfaces registered yet." })) : (registryCards.map((surface) => (_jsxs("div", { style: { marginBottom: 12, border: '1px solid #ccc', borderRadius: 4, padding: 8 }, children: [_jsxs("div", { style: { display: 'flex', alignItems: 'center', gap: 6 }, children: [_jsx("code", { style: { fontWeight: 700 }, children: surface.surfaceId }), _jsx(Badge, { text: "registered", color: "#2d6a4f" }), _jsx("span", { style: { fontSize: 10, color: '#555' }, children: new Date(surface.registeredAt).toLocaleTimeString() }), _jsx("button", { onClick: () => openCodeEditor(dispatch, { ownerAppId, surfaceId: surface.surfaceId }, surface.code, surface.packId), style: {
+                                            fontSize: 10, padding: '1px 6px', borderRadius: 3,
+                                            border: '1px solid #999', background: '#f0f0f0', cursor: 'pointer',
+                                            marginLeft: 'auto',
+                                        }, children: "\u270F\uFE0F Edit" })] }), _jsxs("div", { style: { fontSize: 10, color: '#555', marginTop: 2 }, children: ["code: ", surface.code.length, " chars, ", surface.code.split('\n').length, " lines"] }), _jsx(CodePreview, { code: surface.code })] }, surface.surfaceId))))] }), _jsx(Section, { title: `🗃 Artifacts with Runtime Surfaces (${runtimeArtifacts.length})`, children: runtimeArtifacts.length === 0 ? (_jsx("div", { style: { fontSize: 11, color: '#555' }, children: "No artifacts with runtime surface code." })) : (_jsxs("table", { style: { width: '100%', borderCollapse: 'collapse' }, children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { style: th, children: "Artifact ID" }), _jsx("th", { style: th, children: "Surface ID" }), _jsx("th", { style: th, children: "Title" }), _jsx("th", { style: th, children: "Injection" }), _jsx("th", { style: th, children: "Source" })] }) }), _jsx("tbody", { children: runtimeArtifacts.map(a => (_jsxs("tr", { children: [_jsx("td", { style: td, children: _jsx("code", { children: a.id }) }), _jsx("td", { style: td, children: _jsx("code", { children: a.runtimeSurfaceId }) }), _jsx("td", { style: td, children: a.title }), _jsxs("td", { style: td, children: [a.injectionStatus === 'injected' && _jsx(Badge, { text: "injected", color: "#2d6a4f" }), a.injectionStatus === 'pending' && _jsx(Badge, { text: "pending", color: "#e67e22" }), a.injectionStatus === 'failed' && _jsx(Badge, { text: "failed", color: "#c0392b" }), !a.injectionStatus && _jsx(Badge, { text: "unknown", color: "#666" }), a.injectionError && _jsx("div", { style: { fontSize: 10, color: '#c0392b', marginTop: 2 }, children: a.injectionError })] }), _jsx("td", { style: td, children: a.runtimeSurfaceCode ? `${a.runtimeSurfaceCode.length} chars` : '—' })] }, a.id))) })] })) }), _jsx(Section, { title: `⚙️ Plugin Sessions (${Object.keys(sessions).length})`, children: Object.keys(sessions).length === 0 ? (_jsx("div", { style: { fontSize: 11, color: '#555' }, children: "No active plugin sessions." })) : (_jsxs("table", { style: { width: '100%', borderCollapse: 'collapse' }, children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { style: th, children: "Session ID" }), _jsx("th", { style: th, children: "Bundle" }), _jsx("th", { style: th, children: "Status" }), _jsx("th", { style: th, children: "Current Surface" }), _jsx("th", { style: th, children: "Actions" })] }) }), _jsx("tbody", { children: Object.entries(sessions).map(([sid, s]) => (_jsxs("tr", { children: [_jsx("td", { style: td, children: _jsx("code", { children: sid }) }), _jsx("td", { style: td, children: s.bundleId }), _jsxs("td", { style: td, children: [s.status === 'ready' && _jsx(Badge, { text: "ready", color: "#2d6a4f" }), s.status === 'loading' && _jsx(Badge, { text: "loading", color: "#e67e22" }), s.status === 'error' && _jsx(Badge, { text: "error", color: "#c0392b" }), s.error && _jsx("div", { style: { fontSize: 10, color: '#c0392b', marginTop: 2 }, children: s.error })] }), _jsx("td", { style: td, children: sessionCurrentSurfaceIds.get(sid) ? (_jsx("code", { style: { fontSize: 10 }, children: sessionCurrentSurfaceIds.get(sid) })) : (_jsx("span", { style: { color: '#555' }, children: "\u2014" })) }), _jsx("td", { style: td, children: (() => {
+                                            const currentSurfaceId = sessionCurrentSurfaceIds.get(sid);
+                                            if (!currentSurfaceId) {
+                                                return _jsx("span", { style: { color: '#555' }, children: "\u2014" });
+                                            }
+                                            const bundle = bundlesById.get(s.bundleId);
+                                            const surface = bundle?.surfaces[currentSurfaceId];
+                                            const source = surface ? surfaceSource(surface) : null;
+                                            return (_jsxs("div", { style: { display: 'flex', gap: 6, alignItems: 'center', flexWrap: 'wrap' }, children: [_jsx("button", { onClick: () => launchBundleSurface(s.bundleId, currentSurfaceId), style: {
+                                                            fontSize: 10,
+                                                            padding: '1px 6px',
+                                                            borderRadius: 3,
+                                                            border: '1px solid #999',
+                                                            background: '#f0f0f0',
+                                                            cursor: 'pointer',
+                                                        }, children: "\u25B6 Open" }), source ? (_jsx("button", { onClick: () => openCodeEditor(dispatch, { ownerAppId, surfaceId: currentSurfaceId }, source, s.surfaceTypes?.[currentSurfaceId]), style: {
+                                                            fontSize: 10,
+                                                            padding: '1px 6px',
+                                                            borderRadius: 3,
+                                                            border: '1px solid #999',
+                                                            background: '#f0f0f0',
+                                                            cursor: 'pointer',
+                                                        }, children: "\u270F\uFE0F Edit" })) : null] }));
+                                        })() })] }, sid))) })] })) }), _jsxs(Section, { title: `🧪 JS Sessions (${jsSessions.length})`, children: [_jsxs("div", { style: { fontSize: 11, color: '#555', marginBottom: 8 }, children: ["Plain JavaScript sessions no longer get a full operator table here. Use ", _jsx("strong", { children: "Task Manager" }), " for reset/dispose/focus actions and cross-source session management."] }), _jsxs("div", { style: { display: 'flex', gap: 8, alignItems: 'center', flexWrap: 'wrap' }, children: [_jsx("div", { style: { fontSize: 11, color: '#555' }, children: jsSessions.length === 0
+                                    ? 'No active JS sessions.'
+                                    : `${jsSessions.length} JS session${jsSessions.length === 1 ? '' : 's'} across ${jsSessionSources.length} source${jsSessionSources.length === 1 ? '' : 's'}.` }), _jsx("button", { onClick: () => dispatch(openWindow(buildTaskManagerWindowPayload())), style: {
+                                    fontSize: 10,
+                                    padding: '1px 6px',
+                                    borderRadius: 3,
+                                    border: '1px solid #999',
+                                    background: '#f0f0f0',
+                                    cursor: 'pointer',
+                                }, children: "\uD83D\uDDC2\uFE0F Open Task Manager" })] })] })] }));
+}

package/hypercard/debug/jsSessionDebugRegistry.d.ts

@@ -0,0 +1,11 @@
+import type { JsSessionBroker } from '../../repl/jsSessionBroker';
+export interface JsSessionDebugSource {
+    id: string;
+    title: string;
+    broker: JsSessionBroker;
+}
+export declare function registerJsSessionDebugSource(source: JsSessionDebugSource): void;
+export declare function clearRegisteredJsSessionDebugSources(): void;
+export declare function getRegisteredJsSessionDebugSources(): JsSessionDebugSource[];
+export declare function subscribeJsSessionDebugSources(listener: () => void): () => void;
+export declare function useRegisteredJsSessionDebugSources(): JsSessionDebugSource[];

package/hypercard/debug/jsSessionDebugRegistry.js

@@ -0,0 +1,43 @@
+import { useSyncExternalStore } from 'react';
+const registeredSources = new Map();
+const listeners = new Set();
+let registeredSourcesSnapshot = [];
+function refreshSnapshot() {
+    registeredSourcesSnapshot = Array.from(registeredSources.values());
+}
+function emitChange() {
+    for (const listener of listeners) {
+        listener();
+    }
+}
+export function registerJsSessionDebugSource(source) {
+    if (!source?.id || !source.broker) {
+        return;
+    }
+    if (registeredSources.get(source.id) === source) {
+        return;
+    }
+    registeredSources.set(source.id, source);
+    refreshSnapshot();
+    emitChange();
+}
+export function clearRegisteredJsSessionDebugSources() {
+    if (registeredSources.size === 0) {
+        return;
+    }
+    registeredSources.clear();
+    refreshSnapshot();
+    emitChange();
+}
+export function getRegisteredJsSessionDebugSources() {
+    return registeredSourcesSnapshot;
+}
+export function subscribeJsSessionDebugSources(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+export function useRegisteredJsSessionDebugSources() {
+    return useSyncExternalStore(subscribeJsSessionDebugSources, getRegisteredJsSessionDebugSources, getRegisteredJsSessionDebugSources);
+}

package/hypercard/debug/runtimeDebugApp.d.ts

@@ -0,0 +1,19 @@
+import type { RuntimeBundleDefinition } from '@go-go-golems/os-core';
+import type { OpenWindowPayload } from '@go-go-golems/os-core/desktop-core';
+export declare const HYPERCARD_RUNTIME_DEBUG_APP_ID = "hypercard-runtime-debug";
+export declare const HYPERCARD_RUNTIME_DEBUG_INSTANCE_ID = "stacks";
+export interface BuildRuntimeDebugWindowPayloadOptions {
+    appId?: string;
+    instanceId?: string;
+    title?: string;
+    icon?: string;
+    bounds?: OpenWindowPayload['bounds'];
+    dedupeKey?: string;
+}
+export interface RuntimeDebugAppWindowProps {
+    ownerAppId: string;
+    instanceId: string;
+    bundles?: RuntimeBundleDefinition[];
+}
+export declare function buildRuntimeDebugWindowPayload(options?: BuildRuntimeDebugWindowPayloadOptions): OpenWindowPayload;
+export declare function RuntimeDebugAppWindow({ ownerAppId, instanceId, bundles }: RuntimeDebugAppWindowProps): import("react/jsx-runtime").JSX.Element;

package/hypercard/debug/runtimeDebugApp.js

@@ -0,0 +1,25 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { RuntimeSurfaceDebugWindow } from './RuntimeSurfaceDebugWindow';
+export const HYPERCARD_RUNTIME_DEBUG_APP_ID = 'hypercard-runtime-debug';
+export const HYPERCARD_RUNTIME_DEBUG_INSTANCE_ID = 'stacks';
+export function buildRuntimeDebugWindowPayload(options = {}) {
+    const appId = options.appId ?? HYPERCARD_RUNTIME_DEBUG_APP_ID;
+    const instanceId = options.instanceId ?? HYPERCARD_RUNTIME_DEBUG_INSTANCE_ID;
+    return {
+        id: `window:${appId}:${instanceId}`,
+        title: options.title ?? 'Stacks & Cards',
+        icon: options.icon ?? '🔧',
+        bounds: options.bounds ?? { x: 80, y: 30, w: 560, h: 480 },
+        content: {
+            kind: 'app',
+            appKey: `${appId}:${instanceId}`,
+        },
+        dedupeKey: options.dedupeKey ?? `${appId}:${instanceId}`,
+    };
+}
+export function RuntimeDebugAppWindow({ ownerAppId, instanceId, bundles }) {
+    if (instanceId !== HYPERCARD_RUNTIME_DEBUG_INSTANCE_ID) {
+        return (_jsxs("section", { style: { padding: 12, display: 'grid', gap: 8 }, children: [_jsx("strong", { children: "Stacks & Cards" }), _jsxs("span", { children: ["Unknown runtime debug window instance: ", instanceId] })] }));
+    }
+    return _jsx(RuntimeSurfaceDebugWindow, { ownerAppId: ownerAppId, bundles: bundles });
+}

package/hypercard/debug/runtimeDebugRegistry.d.ts

@@ -0,0 +1,6 @@
+import type { RuntimeBundleDefinition } from '@go-go-golems/os-core';
+export declare function registerRuntimeDebugStacks(stacks: readonly RuntimeBundleDefinition[]): void;
+export declare function getRegisteredRuntimeDebugStacks(): RuntimeBundleDefinition[];
+export declare function clearRegisteredRuntimeDebugStacks(): void;
+export declare function subscribeRuntimeDebugStacks(listener: () => void): () => void;
+export declare function useRegisteredRuntimeDebugStacks(): RuntimeBundleDefinition[];

package/hypercard/debug/runtimeDebugRegistry.js

@@ -0,0 +1,49 @@
+import { useSyncExternalStore } from 'react';
+const registeredStacks = new Map();
+const listeners = new Set();
+let registeredStacksSnapshot = [];
+function refreshSnapshot() {
+    registeredStacksSnapshot = Array.from(registeredStacks.values());
+}
+function emitChange() {
+    for (const listener of listeners) {
+        listener();
+    }
+}
+export function registerRuntimeDebugStacks(stacks) {
+    let changed = false;
+    for (const bundle of stacks) {
+        if (!bundle?.id) {
+            continue;
+        }
+        if (registeredStacks.get(bundle.id) === bundle) {
+            continue;
+        }
+        registeredStacks.set(bundle.id, bundle);
+        changed = true;
+    }
+    if (changed) {
+        refreshSnapshot();
+        emitChange();
+    }
+}
+export function getRegisteredRuntimeDebugStacks() {
+    return registeredStacksSnapshot;
+}
+export function clearRegisteredRuntimeDebugStacks() {
+    if (registeredStacks.size === 0) {
+        return;
+    }
+    registeredStacks.clear();
+    refreshSnapshot();
+    emitChange();
+}
+export function subscribeRuntimeDebugStacks(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+export function useRegisteredRuntimeDebugStacks() {
+    return useSyncExternalStore(subscribeRuntimeDebugStacks, getRegisteredRuntimeDebugStacks, getRegisteredRuntimeDebugStacks);
+}

package/hypercard/editor/CodeEditorWindow.d.ts

@@ -0,0 +1,7 @@
+export interface CodeEditorWindowProps {
+    surfaceId: string;
+    initialCode: string;
+    packId?: string;
+    onSave?: (surfaceId: string, code: string) => void;
+}
+export declare function CodeEditorWindow({ surfaceId, initialCode, packId, onSave }: CodeEditorWindowProps): import("react/jsx-runtime").JSX.Element;

package/hypercard/editor/CodeEditorWindow.js

@@ -0,0 +1,128 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { EditorView, keymap, lineNumbers, drawSelection, highlightActiveLine } from '@codemirror/view';
+import { EditorState } from '@codemirror/state';
+import { javascript } from '@codemirror/lang-javascript';
+import { defaultKeymap, history, historyKeymap } from '@codemirror/commands';
+import { bracketMatching, foldGutter, indentOnInput, syntaxHighlighting } from '@codemirror/language';
+import { oneDark } from '@codemirror/theme-one-dark';
+import { classHighlighter } from '@lezer/highlight';
+import { hasRuntimeSurface, registerRuntimeSurface } from '../../plugin-runtime';
+export function CodeEditorWindow({ surfaceId, initialCode, packId, onSave }) {
+    const editorRef = useRef(null);
+    const viewRef = useRef(null);
+    const [status, setStatus] = useState({ type: 'idle' });
+    const [dirty, setDirty] = useState(false);
+    // Create editor on mount
+    useEffect(() => {
+        if (!editorRef.current)
+            return;
+        const state = EditorState.create({
+            doc: initialCode,
+            extensions: [
+                lineNumbers(),
+                history(),
+                drawSelection(),
+                indentOnInput(),
+                bracketMatching(),
+                foldGutter(),
+                highlightActiveLine(),
+                javascript(),
+                syntaxHighlighting(classHighlighter),
+                oneDark,
+                keymap.of([
+                    ...defaultKeymap,
+                    ...historyKeymap,
+                    {
+                        key: 'Mod-s',
+                        run: () => {
+                            // Trigger save via DOM event — picked up by handleSave
+                            editorRef.current?.dispatchEvent(new CustomEvent('editor-save'));
+                            return true;
+                        },
+                    },
+                ]),
+                EditorView.updateListener.of((update) => {
+                    if (update.docChanged) {
+                        setDirty(true);
+                        setStatus({ type: 'idle' });
+                    }
+                }),
+                EditorView.theme({
+                    '&': { height: '100%', fontSize: '13px' },
+                    '.cm-scroller': { overflow: 'auto' },
+                    '.cm-content': { fontFamily: 'monospace' },
+                }),
+            ],
+        });
+        const view = new EditorView({ state, parent: editorRef.current });
+        viewRef.current = view;
+        return () => {
+            view.destroy();
+            viewRef.current = null;
+        };
+        // Only create once on mount
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    // Listen for Ctrl+S custom event from editor keymap
+    useEffect(() => {
+        const el = editorRef.current;
+        if (!el)
+            return;
+        const listener = () => handleSaveRef.current();
+        el.addEventListener('editor-save', listener);
+        return () => el.removeEventListener('editor-save', listener);
+    }, []);
+    const handleSaveRef = useRef(() => { });
+    const handleSave = useCallback(() => {
+        const view = viewRef.current;
+        if (!view)
+            return;
+        const code = view.state.doc.toString();
+        try {
+            const normalizedPackId = typeof packId === 'string' ? packId.trim() : '';
+            if (!normalizedPackId) {
+                throw new Error(`Runtime surface packId is required for ${surfaceId}`);
+            }
+            registerRuntimeSurface(surfaceId, code, normalizedPackId);
+            setStatus({ type: 'saved', message: `Injected ${surfaceId} — ${code.length} chars` });
+            setDirty(false);
+            onSave?.(surfaceId, code);
+        }
+        catch (err) {
+            setStatus({ type: 'error', message: err instanceof Error ? err.message : String(err) });
+        }
+    }, [packId, surfaceId, onSave]);
+    handleSaveRef.current = handleSave;
+    const handleRevert = useCallback(() => {
+        const view = viewRef.current;
+        if (!view)
+            return;
+        view.dispatch({
+            changes: { from: 0, to: view.state.doc.length, insert: initialCode },
+        });
+        setDirty(false);
+        setStatus({ type: 'idle' });
+    }, [initialCode]);
+    const isRegistered = hasRuntimeSurface(surfaceId);
+    return (_jsxs("div", { style: { display: 'flex', flexDirection: 'column', height: '100%', background: '#282c34' }, children: [_jsxs("div", { style: {
+                    display: 'flex', alignItems: 'center', gap: 8,
+                    padding: '6px 10px', borderBottom: '1px solid #444',
+                    fontSize: 12, color: '#abb2bf', fontFamily: 'monospace',
+                }, children: [_jsx("span", { style: { fontWeight: 700, color: '#e5c07b' }, children: surfaceId }), isRegistered && (_jsx("span", { style: {
+                            fontSize: 10, padding: '1px 6px', borderRadius: 3,
+                            background: '#2d6a4f', color: '#fff', fontWeight: 600,
+                        }, children: "registered" })), dirty && (_jsx("span", { style: { fontSize: 10, color: '#e5c07b' }, children: "\u25CF modified" }))] }), _jsx("div", { ref: editorRef, style: { flex: 1, overflow: 'hidden' } }), _jsxs("div", { style: {
+                    display: 'flex', alignItems: 'center', justifyContent: 'space-between',
+                    padding: '6px 10px', borderTop: '1px solid #444',
+                    fontSize: 11, color: '#abb2bf', fontFamily: 'monospace',
+                }, children: [_jsxs("div", { children: [status.type === 'saved' && (_jsxs("span", { style: { color: '#98c379' }, children: ["\u2713 ", status.message] })), status.type === 'error' && (_jsxs("span", { style: { color: '#e06c75' }, children: ["\u2717 ", status.message] })), status.type === 'idle' && (_jsx("span", { style: { color: '#666' }, children: packId ? 'Ctrl+S to save & inject' : 'Runtime surface packId required before injection' }))] }), _jsxs("div", { style: { display: 'flex', gap: 6 }, children: [_jsx("button", { onClick: handleRevert, disabled: !dirty, style: {
+                                    padding: '3px 10px', fontSize: 11, borderRadius: 3,
+                                    border: '1px solid #555', background: '#3e4451', color: '#abb2bf',
+                                    cursor: dirty ? 'pointer' : 'default', opacity: dirty ? 1 : 0.4,
+                                }, children: "\u21BB Revert" }), _jsx("button", { onClick: handleSave, disabled: !packId, style: {
+                                    padding: '3px 10px', fontSize: 11, borderRadius: 3,
+                                    border: '1px solid #2d6a4f', background: '#2d6a4f', color: '#fff',
+                                    cursor: packId ? 'pointer' : 'default', fontWeight: 600, opacity: packId ? 1 : 0.5,
+                                }, children: "\uD83D\uDCBE Save & Inject" })] })] })] }));
+}

package/hypercard/editor/editorLaunch.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Simple module to pass initial code to the CodeEditorWindow.
+ * Since the editor opens as a windowing-system app (by appKey string),
+ * we can't pass rich props directly. Instead, the caller stashes the
+ * code here before dispatching openWindow, and the editor reads it on mount.
+ */
+import { type OpenWindowPayload, openWindow } from '@go-go-golems/os-core/desktop-core';
+import { type RuntimeSurfaceRef } from './runtimeSurfaceRef';
+type WindowDispatch = (action: ReturnType<typeof openWindow>) => unknown;
+export declare function buildCodeEditorWindowPayload(ref: RuntimeSurfaceRef): OpenWindowPayload;
+/** Stash code for a runtime surface editor and open the window. */
+export declare function openCodeEditor(dispatch: WindowDispatch, ref: RuntimeSurfaceRef, code: string, packId?: string): void;
+/** Get the initial code for a runtime surface editor. Falls back to registry. */
+export declare function getEditorInitialCode(ref: RuntimeSurfaceRef): string;
+export declare function getEditorInitialPackId(ref: RuntimeSurfaceRef): string | undefined;
+export {};

package/hypercard/editor/editorLaunch.js

@@ -0,0 +1,58 @@
+/**
+ * Simple module to pass initial code to the CodeEditorWindow.
+ * Since the editor opens as a windowing-system app (by appKey string),
+ * we can't pass rich props directly. Instead, the caller stashes the
+ * code here before dispatching openWindow, and the editor reads it on mount.
+ */
+import { openWindow } from '@go-go-golems/os-core/desktop-core';
+import { getPendingRuntimeSurfaces } from '../../plugin-runtime';
+import { buildRuntimeSurfaceEditorAppKey, HYPERCARD_TOOLS_APP_ID, } from './runtimeSurfaceRef';
+const pendingCode = new Map();
+const pendingPackIds = new Map();
+function codeKey(ref) {
+    return `${ref.ownerAppId}::${ref.surfaceId}`;
+}
+export function buildCodeEditorWindowPayload(ref) {
+    const key = codeKey(ref);
+    const appKey = buildRuntimeSurfaceEditorAppKey(ref);
+    return {
+        id: `window:${HYPERCARD_TOOLS_APP_ID}:editor:${key}`,
+        title: `✏️ ${ref.surfaceId}`,
+        icon: '✏️',
+        bounds: { x: 100, y: 40, w: 600, h: 500 },
+        content: { kind: 'app', appKey },
+        dedupeKey: `runtime-surface-editor:${key}`,
+    };
+}
+/** Stash code for a runtime surface editor and open the window. */
+export function openCodeEditor(dispatch, ref, code, packId) {
+    pendingCode.set(codeKey(ref), code);
+    if (typeof packId === 'string' && packId.trim().length > 0) {
+        pendingPackIds.set(codeKey(ref), packId.trim());
+    }
+    dispatch(openWindow(buildCodeEditorWindowPayload(ref)));
+}
+/** Get the initial code for a runtime surface editor. Falls back to registry. */
+export function getEditorInitialCode(ref) {
+    const key = codeKey(ref);
+    const stashed = pendingCode.get(key);
+    if (stashed !== undefined) {
+        pendingCode.delete(key);
+        return stashed;
+    }
+    // Fallback: look up from the runtime surface registry.
+    const surfaces = getPendingRuntimeSurfaces();
+    const found = surfaces.find((surface) => surface.surfaceId === ref.surfaceId);
+    return found?.code ?? `// No code found for surface: ${ref.surfaceId}\n`;
+}
+export function getEditorInitialPackId(ref) {
+    const key = codeKey(ref);
+    const stashed = pendingPackIds.get(key);
+    if (stashed !== undefined) {
+        pendingPackIds.delete(key);
+        return stashed;
+    }
+    const surfaces = getPendingRuntimeSurfaces();
+    const found = surfaces.find((surface) => surface.surfaceId === ref.surfaceId);
+    return found?.packId;
+}

package/hypercard/editor/runtimeSurfaceRef.d.ts

@@ -0,0 +1,8 @@
+export declare const HYPERCARD_TOOLS_APP_ID = "hypercard-tools";
+export interface RuntimeSurfaceRef {
+    ownerAppId: string;
+    surfaceId: string;
+}
+export declare function encodeRuntimeSurfaceEditorInstanceId(ref: RuntimeSurfaceRef): string;
+export declare function decodeRuntimeSurfaceEditorInstanceId(instanceId: string): RuntimeSurfaceRef | null;
+export declare function buildRuntimeSurfaceEditorAppKey(ref: RuntimeSurfaceRef): string;

package/hypercard/editor/runtimeSurfaceRef.js

@@ -0,0 +1,60 @@
+export const HYPERCARD_TOOLS_APP_ID = 'hypercard-tools';
+const INSTANCE_KIND_EDITOR = 'editor';
+const INSTANCE_DELIMITER = '~';
+const APP_ID_RE = /^[a-z][a-z0-9-]*$/;
+function clean(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function assertValidOwnerAppId(ownerAppId) {
+    if (!APP_ID_RE.test(ownerAppId)) {
+        throw new Error(`Invalid owner app id "${ownerAppId}". Expected /^[a-z][a-z0-9-]*$/.`);
+    }
+}
+function assertValidSurfaceId(surfaceId) {
+    if (surfaceId.trim().length === 0) {
+        throw new Error('Invalid runtime surface id: expected a non-empty surface id.');
+    }
+}
+export function encodeRuntimeSurfaceEditorInstanceId(ref) {
+    const ownerAppId = clean(ref.ownerAppId);
+    const surfaceId = clean(ref.surfaceId);
+    if (!ownerAppId) {
+        throw new Error('Invalid owner app id: expected a non-empty owner app id.');
+    }
+    if (!surfaceId) {
+        throw new Error('Invalid runtime surface id: expected a non-empty surface id.');
+    }
+    assertValidOwnerAppId(ownerAppId);
+    assertValidSurfaceId(surfaceId);
+    return `${INSTANCE_KIND_EDITOR}${INSTANCE_DELIMITER}${encodeURIComponent(ownerAppId)}${INSTANCE_DELIMITER}${encodeURIComponent(surfaceId)}`;
+}
+export function decodeRuntimeSurfaceEditorInstanceId(instanceId) {
+    const raw = clean(instanceId);
+    if (!raw) {
+        return null;
+    }
+    const parts = raw.split(INSTANCE_DELIMITER);
+    if (parts.length !== 3 || parts[0] !== INSTANCE_KIND_EDITOR) {
+        return null;
+    }
+    try {
+        const ownerAppId = clean(decodeURIComponent(parts[1] ?? ''));
+        const surfaceId = clean(decodeURIComponent(parts[2] ?? ''));
+        if (!ownerAppId || !surfaceId) {
+            return null;
+        }
+        assertValidOwnerAppId(ownerAppId);
+        assertValidSurfaceId(surfaceId);
+        return { ownerAppId, surfaceId };
+    }
+    catch {
+        return null;
+    }
+}
+export function buildRuntimeSurfaceEditorAppKey(ref) {
+    return `${HYPERCARD_TOOLS_APP_ID}:${encodeRuntimeSurfaceEditorInstanceId(ref)}`;
+}

package/hypercard/index.d.ts

@@ -0,0 +1,12 @@
+export * from './artifacts/artifactRuntime';
+export * from './artifacts/artifactsSelectors';
+export * from './artifacts/artifactsSlice';
+export * from './debug/RuntimeSurfaceDebugWindow';
+export * from './debug/runtimeDebugApp';
+export * from './debug/runtimeDebugRegistry';
+export * from './debug/jsSessionDebugRegistry';
+export * from './editor/CodeEditorWindow';
+export * from './editor/editorLaunch';
+export * from './editor/runtimeSurfaceRef';
+export * from './task-manager';
+export * from './timeline/hypercardCard';