@faclon-labs/app-sdk 0.1.0 → 0.3.0

package/vendor/map-engine/commands/index.d.ts

@@ -0,0 +1,2 @@
+export { createPostMessageBridge, connectToMap, type PostMessageBridgeOptions } from './post-message.js';
+export { mapWebMcpTools, type WebMcpTool } from './webmcp.js';

package/vendor/map-engine/commands/index.js

@@ -0,0 +1,2 @@
+export { createPostMessageBridge, connectToMap } from './post-message.js';
+export { mapWebMcpTools } from './webmcp.js';

package/vendor/map-engine/commands/post-message.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Map commands over `postMessage` (doc 28 G6): a page that shows a map lets its host (an assistant panel, an
+ * iframe parent) drive it, and tells the host what happens on the map. Only listed origins are heard; every run
+ * is the runtime's `execute`, so it is checked whole and audited with its origin.
+ *
+ *   host → map   { kind: 'map-engine/command', id, version: 1, commands, origin? }
+ *   map  → host  { kind: 'map-engine/result', id, result }
+ *   map  → host  { kind: 'map-engine/event', event, payload }   (the events the bridge forwards)
+ */
+import { type CommandResult, type MapCommand } from '../core/commands.js';
+import type { MapRuntime, MapRuntimeEvents } from '../runtime/types.js';
+export interface PostMessageBridgeOptions {
+    /** Origins allowed to send commands and to receive events. Required: there is no "any origin". */
+    allowedOrigins: string[];
+    /** Where to listen. Default: `window`. */
+    listenOn?: Pick<Window, 'addEventListener' | 'removeEventListener'>;
+    /** Runtime events forwarded to the allowed host(s). Default: selection, proposal, annotation, command. */
+    forward?: Array<keyof MapRuntimeEvents>;
+    /** Where forwarded events go (e.g. `window.parent`). Default: the window that last sent a command. */
+    host?: Pick<Window, 'postMessage'>;
+}
+/** Starts the bridge; returns a function that stops it. */
+export declare function createPostMessageBridge(runtime: MapRuntime, options: PostMessageBridgeOptions): () => void;
+/** The host side: send commands to a map in another window or frame and wait for the answer. */
+export declare function connectToMap(mapWindow: Pick<Window, 'postMessage'>, mapOrigin: string, options?: {
+    listenOn?: Pick<Window, 'addEventListener' | 'removeEventListener'>;
+    origin?: string;
+    timeoutMs?: number;
+}): {
+    execute(commands: MapCommand | MapCommand[]): Promise<CommandResult>;
+    close(): void;
+};

package/vendor/map-engine/commands/post-message.js

@@ -0,0 +1,77 @@
+/**
+ * Map commands over `postMessage` (doc 28 G6): a page that shows a map lets its host (an assistant panel, an
+ * iframe parent) drive it, and tells the host what happens on the map. Only listed origins are heard; every run
+ * is the runtime's `execute`, so it is checked whole and audited with its origin.
+ *
+ *   host → map   { kind: 'map-engine/command', id, version: 1, commands, origin? }
+ *   map  → host  { kind: 'map-engine/result', id, result }
+ *   map  → host  { kind: 'map-engine/event', event, payload }   (the events the bridge forwards)
+ */
+import { COMMAND_VERSION } from '../core/commands.js';
+const isCommandMessage = (d) => typeof d === 'object' && d !== null && d.kind === 'map-engine/command';
+/** Starts the bridge; returns a function that stops it. */
+export function createPostMessageBridge(runtime, options) {
+    if (!options.allowedOrigins?.length || options.allowedOrigins.includes('*'))
+        throw new Error('createPostMessageBridge: list the allowed origins (no "*")');
+    const allowed = new Set(options.allowedOrigins);
+    const listener = options.listenOn ?? window;
+    let host = options.host ? { win: options.host, origin: options.allowedOrigins[0] } : null;
+    const onMessage = (event) => {
+        if (!allowed.has(event.origin) || !isCommandMessage(event.data))
+            return;
+        const msg = event.data;
+        const reply = event.source;
+        if (reply && !options.host)
+            host = { win: reply, origin: event.origin };
+        const answer = (result) => reply?.postMessage({ kind: 'map-engine/result', id: msg.id, result }, event.origin);
+        if (msg.version !== undefined && msg.version !== COMMAND_VERSION) {
+            answer({ ok: false, applied: 0, error: { index: -1, reason: `command version ${msg.version} is not supported (this map speaks ${COMMAND_VERSION})` } });
+            return;
+        }
+        const origin = `${typeof msg.origin === 'string' && msg.origin ? msg.origin : 'host'}@${event.origin}`;
+        runtime.execute(msg.commands, { origin }).then(answer, (e) => answer({ ok: false, applied: 0, error: { index: -1, reason: e instanceof Error ? e.message : String(e) } }));
+    };
+    listener.addEventListener('message', onMessage);
+    const offs = (options.forward ?? ['selection', 'proposal', 'annotation', 'command']).map((event) => runtime.on(event, (payload) => {
+        if (host)
+            host.win.postMessage({ kind: 'map-engine/event', event, payload: JSON.parse(JSON.stringify(payload ?? null)) }, host.origin);
+    }));
+    return () => {
+        listener.removeEventListener('message', onMessage);
+        for (const off of offs)
+            off();
+    };
+}
+/** The host side: send commands to a map in another window or frame and wait for the answer. */
+export function connectToMap(mapWindow, mapOrigin, options = {}) {
+    const listenOn = options.listenOn ?? window;
+    let next = 1;
+    const waiting = new Map();
+    const onMessage = (event) => {
+        const d = event.data;
+        if (event.origin !== mapOrigin || d?.kind !== 'map-engine/result' || d.id === undefined)
+            return;
+        waiting.get(d.id)?.(d.result);
+        waiting.delete(d.id);
+    };
+    listenOn.addEventListener('message', onMessage);
+    return {
+        execute(commands) {
+            const id = next++;
+            return new Promise((resolve) => {
+                waiting.set(id, resolve);
+                mapWindow.postMessage({ kind: 'map-engine/command', id, version: COMMAND_VERSION, commands, ...(options.origin ? { origin: options.origin } : {}) }, mapOrigin);
+                setTimeout(() => {
+                    if (!waiting.has(id))
+                        return;
+                    waiting.delete(id);
+                    resolve({ ok: false, applied: 0, error: { index: -1, reason: 'the map did not answer' } });
+                }, options.timeoutMs ?? 10_000);
+            });
+        },
+        close() {
+            listenOn.removeEventListener('message', onMessage);
+            waiting.clear();
+        },
+    };
+}

package/vendor/map-engine/commands/webmcp.d.ts

@@ -0,0 +1,17 @@
+import type { MapRuntime } from '../runtime/types.js';
+export interface WebMcpTool {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    execute: (input: Record<string, unknown>) => Promise<{
+        content: Array<{
+            type: 'text';
+            text: string;
+        }>;
+    }>;
+}
+/** The map's tools for an agent: read the map, find objects on it, run commands. */
+export declare function mapWebMcpTools(runtime: MapRuntime, options?: {
+    origin?: string;
+    prefix?: string;
+}): WebMcpTool[];

package/vendor/map-engine/commands/webmcp.js

@@ -0,0 +1,59 @@
+/**
+ * Map commands as WebMCP tools (doc 28 G6): an agent in the browser reads the map and drives it with the same
+ * command set, through `execute` — checked whole and audited with its origin. The application registers them
+ * (`document.modelContext.registerTool(tool)`); the engine only builds them.
+ */
+import { COMMAND_TYPES } from '../core/commands.js';
+const text = (value) => ({ content: [{ type: 'text', text: JSON.stringify(value) }] });
+const label = (p, id) => String(p?.label ?? p?.name ?? id);
+/** The map's tools for an agent: read the map, find objects on it, run commands. */
+export function mapWebMcpTools(runtime, options = {}) {
+    const origin = options.origin ?? 'agent:webmcp';
+    const n = (name) => `${options.prefix ?? 'map_'}${name}`;
+    return [
+        {
+            name: n('read'),
+            description: 'Read the map: camera, layers (id, kind, visible, status), selection, time (live or replay), highlight and open proposals. Call this first.',
+            inputSchema: { type: 'object', properties: {} },
+            async execute() {
+                const v = runtime.getViewport();
+                return text({
+                    viewport: { center: v.center, zoom: v.zoom, bounds: v.bounds },
+                    layers: runtime.getLayers().map((l) => ({ id: l.id, kind: l.visualization.type, visible: l.visible, type: l.source.ontologyType, status: runtime.getLayerStatus(l.id) })),
+                    selection: runtime.getSelection().objectIds,
+                    time: runtime.getTime(),
+                    highlight: runtime.getHighlight(),
+                    proposals: runtime.getProposals().map((p) => ({ id: p.id, label: p.label, origin: p.origin })),
+                });
+            },
+        },
+        {
+            name: n('find'),
+            description: 'Find objects loaded on the map, by type and/or property conditions (op: eq, neq, gt, gte, lt, lte, between, in, exists). Returns ids, labels and positions (at most 50).',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    ontologyType: { type: 'string' },
+                    where: { type: 'array', items: { type: 'object', properties: { property: { type: 'string' }, op: { type: 'string' }, value: {} }, required: ['property', 'op'] } },
+                },
+            },
+            async execute(input) {
+                const where = Array.isArray(input.where) ? input.where : undefined;
+                const found = runtime.queryLoaded({ ...(typeof input.ontologyType === 'string' ? { ontologyType: input.ontologyType } : {}), ...(where ? { where } : {}) });
+                return text(found.slice(0, 50).map((o) => ({ id: o.objectId, label: label(o.properties, o.objectId), geometry: o.geometry.type === 'Point' ? o.geometry.coordinates : o.geometry.type })));
+            },
+        },
+        {
+            name: n('command'),
+            description: `Run map commands as one unit: all are checked first, then applied in order, or none. Types: ${COMMAND_TYPES.join(', ')}. Example: [{"type":"flyTo","objectId":"x"},{"type":"highlight","objectIds":["x"],"durationMs":8000}]. drawProposal suggests a geometry a person must accept.`,
+            inputSchema: {
+                type: 'object',
+                properties: { commands: { type: 'array', items: { type: 'object', properties: { type: { type: 'string', enum: [...COMMAND_TYPES] } }, required: ['type'] } } },
+                required: ['commands'],
+            },
+            async execute(input) {
+                return text(await runtime.execute((input.commands ?? []), { origin }));
+            },
+        },
+    ];
+}

package/vendor/map-engine/core/commands.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Map commands (doc 28 G6): one versioned, declarative set that an agent, an iframe host or any part of an app can
+ * send. Each command maps onto a runtime method — the command set adds no behaviour of its own. A list of commands is
+ * checked as a whole before anything runs: an unknown or invalid command refuses the whole list, never half of it.
+ */
+import type { BoundingBox, Geometry, Position, PropertyCondition } from './types.js';
+export declare const COMMAND_VERSION = 1;
+export type MapCommand = {
+    type: 'showLayer';
+    layerId: string;
+} | {
+    type: 'hideLayer';
+    layerId: string;
+}
+/** Narrows what a layer loads; `where: []` clears the filter. */
+ | {
+    type: 'setFilter';
+    layerId: string;
+    where: PropertyCondition[];
+} | {
+    type: 'flyTo';
+    objectId?: string;
+    position?: Position;
+    zoom?: number;
+} | {
+    type: 'fitTo';
+    bounds?: BoundingBox;
+    objectIds?: string[];
+} | {
+    type: 'select';
+    objectIds: string[];
+} | {
+    type: 'clearSelection';
+} | {
+    type: 'highlight';
+    objectIds: string[];
+    durationMs?: number;
+    color?: string;
+} | {
+    type: 'clearHighlight';
+}
+/** Asks the application to open its details view for an object (the engine has no inspector of its own). */
+ | {
+    type: 'openInspector';
+    objectId: string;
+}
+/** `at` ISO 8601, or 'live'. */
+ | {
+    type: 'setTime';
+    at: string;
+}
+/** Asks the application's timeline to play or pause (the application owns time, ADR-010). */
+ | {
+    type: 'play';
+    speed?: number;
+} | {
+    type: 'pause';
+} | {
+    type: 'drawProposal';
+    geometry: Geometry;
+    label?: string;
+    note?: string;
+    id?: string;
+} | {
+    type: 'clearProposals';
+};
+export type MapCommandType = MapCommand['type'];
+export interface CommandResult {
+    ok: boolean;
+    /** How many commands ran (all of them, or none). */
+    applied: number;
+    /** Why the list was refused: the index and reason of the first bad command. */
+    error?: {
+        index: number;
+        reason: string;
+    };
+    /** Values some commands return (e.g. the id of a drawn proposal), by index. */
+    results?: Record<number, unknown>;
+}
+export declare const COMMAND_TYPES: readonly ("showLayer" | "hideLayer" | "setFilter" | "flyTo" | "fitTo" | "select" | "clearSelection" | "highlight" | "clearHighlight" | "openInspector" | "setTime" | "play" | "pause" | "drawProposal" | "clearProposals")[];
+/** Shape checks of one command (references to layers and objects are checked by the runtime). Null when fine. */
+export declare function commandProblem(c: unknown): string | null;

package/vendor/map-engine/core/commands.js

@@ -0,0 +1,46 @@
+export const COMMAND_VERSION = 1;
+const TYPES = ['showLayer', 'hideLayer', 'setFilter', 'flyTo', 'fitTo', 'select', 'clearSelection', 'highlight', 'clearHighlight', 'openInspector', 'setTime', 'play', 'pause', 'drawProposal', 'clearProposals'];
+export const COMMAND_TYPES = TYPES;
+const str = (v) => typeof v === 'string' && v !== '';
+const ids = (v) => Array.isArray(v) && v.length > 0 && v.every(str);
+const isPos = (p) => {
+    const q = p;
+    return !!q && typeof q.latitude === 'number' && typeof q.longitude === 'number' && Math.abs(q.latitude) <= 90 && Math.abs(q.longitude) <= 180;
+};
+/** Shape checks of one command (references to layers and objects are checked by the runtime). Null when fine. */
+export function commandProblem(c) {
+    if (typeof c !== 'object' || c === null)
+        return 'a command must be an object';
+    const cmd = c;
+    if (!TYPES.includes(cmd.type))
+        return `unknown command type "${String(cmd.type)}" (known: ${TYPES.join(', ')})`;
+    switch (cmd.type) {
+        case 'showLayer':
+        case 'hideLayer':
+            return str(cmd.layerId) ? null : 'layerId is required';
+        case 'setFilter':
+            return !str(cmd.layerId) ? 'layerId is required' : Array.isArray(cmd.where) ? null : 'where must be an array of conditions';
+        case 'flyTo':
+            if (!str(cmd.objectId) && !isPos(cmd.position))
+                return 'flyTo needs an objectId or a position';
+            return cmd.zoom === undefined || (typeof cmd.zoom === 'number' && cmd.zoom >= 0 && cmd.zoom <= 24) ? null : 'zoom must be within [0, 24]';
+        case 'fitTo':
+            return ids(cmd.objectIds) || (typeof cmd.bounds === 'object' && cmd.bounds !== null) ? null : 'fitTo needs bounds or objectIds';
+        case 'select':
+            return Array.isArray(cmd.objectIds) && cmd.objectIds.every(str) ? null : 'objectIds must be an array of ids';
+        case 'highlight':
+            if (!ids(cmd.objectIds))
+                return 'objectIds must be a non-empty array of ids';
+            return cmd.durationMs === undefined || (typeof cmd.durationMs === 'number' && cmd.durationMs > 0) ? null : 'durationMs must be > 0';
+        case 'openInspector':
+            return str(cmd.objectId) ? null : 'objectId is required';
+        case 'setTime':
+            return cmd.at === 'live' || (str(cmd.at) && Number.isFinite(Date.parse(String(cmd.at)))) ? null : 'at must be an ISO 8601 time or "live"';
+        case 'play':
+            return cmd.speed === undefined || (typeof cmd.speed === 'number' && cmd.speed > 0) ? null : 'speed must be > 0';
+        case 'drawProposal':
+            return typeof cmd.geometry === 'object' && cmd.geometry !== null ? null : 'geometry is required';
+        default:
+            return null;
+    }
+}

package/vendor/map-engine/core/emitter.d.ts

@@ -0,0 +1,9 @@
+import type { Unsubscribe } from './types.js';
+/** A small typed event emitter. One listener throwing does not stop the others. */
+export declare class Emitter<Events extends Record<string, unknown>> {
+    private readonly listeners;
+    on<K extends keyof Events>(event: K, listener: (payload: Events[K]) => void): Unsubscribe;
+    emit<K extends keyof Events>(event: K, payload: Events[K]): void;
+    clear(): void;
+    listenerCount(event: keyof Events): number;
+}

package/vendor/map-engine/core/emitter.js

@@ -0,0 +1,38 @@
+/** A small typed event emitter. One listener throwing does not stop the others. */
+export class Emitter {
+    listeners = new Map();
+    on(event, listener) {
+        let set = this.listeners.get(event);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(event, set);
+        }
+        const fn = listener;
+        set.add(fn);
+        return () => {
+            set.delete(fn);
+        };
+    }
+    emit(event, payload) {
+        const set = this.listeners.get(event);
+        if (!set)
+            return;
+        for (const fn of [...set]) {
+            try {
+                fn(payload);
+            }
+            catch (error) {
+                // A faulty listener must not break the runtime or other listeners.
+                queueMicrotask(() => {
+                    throw error;
+                });
+            }
+        }
+    }
+    clear() {
+        this.listeners.clear();
+    }
+    listenerCount(event) {
+        return this.listeners.get(event)?.size ?? 0;
+    }
+}

package/vendor/map-engine/core/equal.d.ts

@@ -0,0 +1,2 @@
+/** Structural equality for plain data (objects, arrays, primitives). Used to keep scene patches minimal. */
+export declare function deepEqual(a: unknown, b: unknown): boolean;

package/vendor/map-engine/core/equal.js

@@ -0,0 +1,28 @@
+/** Structural equality for plain data (objects, arrays, primitives). Used to keep scene patches minimal. */
+export function deepEqual(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null)
+        return false;
+    if (Array.isArray(a)) {
+        if (!Array.isArray(b) || a.length !== b.length)
+            return false;
+        for (let i = 0; i < a.length; i++)
+            if (!deepEqual(a[i], b[i]))
+                return false;
+        return true;
+    }
+    if (Array.isArray(b))
+        return false;
+    const ka = Object.keys(a);
+    const kb = Object.keys(b);
+    if (ka.length !== kb.length)
+        return false;
+    for (const k of ka) {
+        if (!Object.prototype.hasOwnProperty.call(b, k))
+            return false;
+        if (!deepEqual(a[k], b[k]))
+            return false;
+    }
+    return true;
+}

package/vendor/map-engine/core/errors.d.ts

@@ -0,0 +1,20 @@
+export type MapEngineErrorCode = 'INVALID_GEOMETRY' | 'INVALID_VIEWPORT' | 'INVALID_LAYER' | 'INVALID_GEOFENCE' | 'DUPLICATE_LAYER' | 'UNKNOWN_LAYER' | 'PROVIDER_ERROR' | 'RENDERER_ERROR' | 'MISSING_CAPABILITY'
+/** A source stamped data ahead of this clock (doc 14 freshness): it is shown, but its time is not trusted for ordering. */
+ | 'CLOCK_SKEW'
+/** The provider refused data for this user (doc 28 G13): shown as a "no access" state, not as a failure. */
+ | 'ACCESS_DENIED'
+/** A URL that leaves the site in an offline profile (doc 28 G14). */
+ | 'OFFLINE_VIOLATION'
+/** A map command was refused (unknown, invalid or not allowed); nothing of it was applied (doc 28 G6). */
+ | 'INVALID_COMMAND' | 'NOT_MOUNTED' | 'ALREADY_MOUNTED' | 'DESTROYED';
+/** Which part of the system an error comes from (doc §63): data, configuration, geometry, renderer, lifecycle. */
+export type MapEngineErrorSource = 'geometry' | 'config' | 'provider' | 'data' | 'renderer' | 'lifecycle';
+export declare class MapEngineError extends Error {
+    readonly code: MapEngineErrorCode;
+    readonly source: MapEngineErrorSource;
+    readonly details?: Record<string, unknown>;
+    constructor(code: MapEngineErrorCode, message: string, details?: Record<string, unknown>, options?: {
+        cause?: unknown;
+    });
+}
+export declare function isAbortError(error: unknown): boolean;

package/vendor/map-engine/core/errors.js

@@ -0,0 +1,34 @@
+const SOURCE = {
+    INVALID_GEOMETRY: 'geometry',
+    INVALID_VIEWPORT: 'config',
+    INVALID_LAYER: 'config',
+    INVALID_GEOFENCE: 'config',
+    DUPLICATE_LAYER: 'config',
+    UNKNOWN_LAYER: 'config',
+    PROVIDER_ERROR: 'provider',
+    MISSING_CAPABILITY: 'data',
+    CLOCK_SKEW: 'data',
+    ACCESS_DENIED: 'provider',
+    OFFLINE_VIOLATION: 'config',
+    INVALID_COMMAND: 'config',
+    RENDERER_ERROR: 'renderer',
+    NOT_MOUNTED: 'lifecycle',
+    ALREADY_MOUNTED: 'lifecycle',
+    DESTROYED: 'lifecycle',
+};
+export class MapEngineError extends Error {
+    code;
+    source;
+    details;
+    constructor(code, message, details, options) {
+        super(message, options);
+        this.name = 'MapEngineError';
+        this.code = code;
+        this.source = SOURCE[code];
+        if (details)
+            this.details = details;
+    }
+}
+export function isAbortError(error) {
+    return typeof error === 'object' && error !== null && error.name === 'AbortError';
+}

package/vendor/map-engine/core/geometry-family.d.ts

@@ -0,0 +1,3 @@
+import type { GeometryFamily, GeometryType } from './types.js';
+/** Point, line or area: what a layer of that kind can draw. A MultiPoint is drawn by a marker layer, and so on. */
+export declare function geometryFamily(type: GeometryType): GeometryFamily;

package/vendor/map-engine/core/geometry-family.js

@@ -0,0 +1,13 @@
+const FAMILY = {
+    Point: 'point',
+    MultiPoint: 'point',
+    LineString: 'line',
+    MultiLineString: 'line',
+    Polygon: 'area',
+    MultiPolygon: 'area',
+    Circle: 'area',
+};
+/** Point, line or area: what a layer of that kind can draw. A MultiPoint is drawn by a marker layer, and so on. */
+export function geometryFamily(type) {
+    return FAMILY[type];
+}

package/vendor/map-engine/core/index.d.ts

@@ -0,0 +1,4 @@
+export type * from './types.js';
+export { MapEngineError, isAbortError, type MapEngineErrorCode } from './errors.js';
+export { Emitter } from './emitter.js';
+export { deepEqual } from './equal.js';

package/vendor/map-engine/core/index.js

@@ -0,0 +1,3 @@
+export { MapEngineError, isAbortError } from './errors.js';
+export { Emitter } from './emitter.js';
+export { deepEqual } from './equal.js';