@fps-games/editor 0.2.0-beta.3 → 0.2.1-beta.1

package/node_modules/@fps-games/editor-core/dist/editor-tools.js

@@ -0,0 +1,613 @@
+const ENABLED = Object.freeze({ state: 'enabled' });
+export function createEditorToolRegistry() {
+    const registrations = new Map();
+    const listeners = new Set();
+    let revision = 0;
+    const snapshot = () => Object.freeze({
+        revision,
+        registrations: Object.freeze([...registrations.values()].sort(compareToolRegistrations)),
+    });
+    const publish = () => {
+        const next = snapshot();
+        for (const listener of [...listeners])
+            listener(next);
+    };
+    const registry = {
+        register(registration) {
+            const frozen = snapshotEditorToolRegistration(registration);
+            const id = frozen.definition.id;
+            if (registrations.has(id))
+                throw new Error(`Duplicate editor tool id: ${id}`);
+            registrations.set(id, frozen);
+            revision += 1;
+            publish();
+            let active = true;
+            return () => {
+                if (!active)
+                    return;
+                active = false;
+                if (registrations.get(id) !== frozen)
+                    return;
+                registrations.delete(id);
+                revision += 1;
+                publish();
+            };
+        },
+        get: id => registrations.get(id),
+        snapshot,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => { listeners.delete(listener); };
+        },
+    };
+    return Object.freeze(registry);
+}
+export function createEditorToolManager(options) {
+    const listeners = new Set();
+    let context = options.context ? snapshotEditingContext(options.context) : null;
+    let active = null;
+    const pendingCleanups = new Set();
+    let activationGeneration = 0;
+    let revision = 0;
+    let disposed = false;
+    let disposeRequested = false;
+    let registrySubscribed = true;
+    let backgroundFailure = null;
+    let queue = Promise.resolve();
+    const managerSnapshot = () => Object.freeze({
+        revision,
+        context,
+        activeToolId: active?.registration.definition.id ?? null,
+        activationGeneration,
+        tools: Object.freeze(options.registry.snapshot().registrations.map(registration => (createToolPresentation(registration.definition, context, active?.registration.definition.id ?? null)))),
+    });
+    const publish = () => {
+        revision += 1;
+        const next = managerSnapshot();
+        for (const listener of [...listeners])
+            listener(next);
+    };
+    const enqueue = (operation) => {
+        const result = queue.then(operation, operation);
+        queue = result.catch(() => { });
+        return result;
+    };
+    const requireContext = () => {
+        if (!context)
+            throw new Error('Editor Tool activation requires an active Editing Context.');
+        return context;
+    };
+    const resolveFallbackId = (removed) => {
+        const candidates = [
+            removed?.definition.fallbackToolId,
+            options.fallbackToolId,
+        ];
+        for (const candidate of candidates) {
+            if (!candidate || !options.registry.get(candidate))
+                continue;
+            if (resolveToolAvailability(options.registry.get(candidate).definition, context).state === 'enabled') {
+                return candidate;
+            }
+        }
+        return options.registry.snapshot().registrations.find(registration => (registration.definition.kind === 'primary'
+            && resolveToolAvailability(registration.definition, context).state === 'enabled'))?.definition.id ?? null;
+    };
+    const cleanupRuntime = async (current, reason) => {
+        const cleanup = current.cleanup ?? (current.cleanup = {
+            reason,
+            cancelComplete: !current.runtime.cancel,
+            deactivateComplete: !current.runtime.deactivate,
+            disposeComplete: !current.runtime.dispose,
+        });
+        pendingCleanups.add(current);
+        const errors = [];
+        if (!cleanup.cancelComplete) {
+            try {
+                await current.runtime.cancel(cleanup.reason);
+                cleanup.cancelComplete = true;
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        if (!cleanup.deactivateComplete) {
+            try {
+                await current.runtime.deactivate(cleanup.reason);
+                cleanup.deactivateComplete = true;
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        if (!cleanup.disposeComplete) {
+            try {
+                await current.runtime.dispose();
+                cleanup.disposeComplete = true;
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        if (cleanup.cancelComplete && cleanup.deactivateComplete && cleanup.disposeComplete) {
+            pendingCleanups.delete(current);
+        }
+        if (errors.length > 0)
+            throw createAggregateError('Editor Tool cleanup failed.', errors);
+    };
+    const retryPendingCleanups = async () => {
+        const errors = [];
+        for (const pending of [...pendingCleanups]) {
+            try {
+                await cleanupRuntime(pending, pending.cleanup?.reason ?? 'manager-dispose');
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        if (errors.length > 0)
+            throw createAggregateError('Editor Tool cleanup retry failed.', errors);
+    };
+    const createRuntimeLease = (registration, runtime) => ({ registration, runtime, cleanup: null });
+    const activateNow = async (toolId, allowPendingCleanup = false) => {
+        if (disposed || disposeRequested)
+            throw new Error('Editor Tool Manager is disposed.');
+        if (!allowPendingCleanup && pendingCleanups.size > 0)
+            await retryPendingCleanups();
+        const registration = options.registry.get(toolId);
+        if (!registration)
+            throw new Error(`Unknown editor tool: ${toolId}`);
+        if (registration.definition.kind !== 'primary') {
+            throw new Error(`Editor Tool Manager can only activate primary tools: ${toolId}`);
+        }
+        const nextContext = requireContext();
+        const availability = resolveToolAvailability(registration.definition, nextContext);
+        if (availability.state !== 'enabled') {
+            throw new Error(`Editor tool is ${availability.state}: ${toolId} (${availability.reason})`);
+        }
+        if (active?.registration.definition.id === toolId)
+            return;
+        activationGeneration += 1;
+        const previous = active;
+        active = null;
+        if (previous) {
+            try {
+                await cleanupRuntime(previous, 'tool-change');
+            }
+            catch (error) {
+                publish();
+                throw error;
+            }
+        }
+        let candidate = null;
+        try {
+            const runtime = registration.createRuntime(Object.freeze({ definition: registration.definition }));
+            assertEditorToolRuntime(runtime, toolId);
+            candidate = createRuntimeLease(registration, runtime);
+            await candidate.runtime.activate(nextContext);
+            active = candidate;
+            publish();
+        }
+        catch (error) {
+            const rollbackErrors = [error];
+            if (candidate) {
+                try {
+                    await cleanupRuntime(candidate, 'activation-rollback');
+                }
+                catch (cleanupError) {
+                    rollbackErrors.push(cleanupError);
+                }
+            }
+            if (previous && options.registry.get(previous.registration.definition.id) === previous.registration) {
+                let rollbackLease = null;
+                try {
+                    const rollbackRuntime = previous.registration.createRuntime(Object.freeze({
+                        definition: previous.registration.definition,
+                    }));
+                    assertEditorToolRuntime(rollbackRuntime, previous.registration.definition.id);
+                    rollbackLease = createRuntimeLease(previous.registration, rollbackRuntime);
+                    await rollbackLease.runtime.activate(nextContext);
+                    active = rollbackLease;
+                }
+                catch (restoreError) {
+                    rollbackErrors.push(restoreError);
+                    active = null;
+                    if (rollbackLease) {
+                        try {
+                            await cleanupRuntime(rollbackLease, 'activation-rollback');
+                        }
+                        catch (cleanupError) {
+                            rollbackErrors.push(cleanupError);
+                        }
+                    }
+                    const fallbackId = resolveFallbackId(registration);
+                    if (fallbackId) {
+                        try {
+                            await activateNow(fallbackId, true);
+                        }
+                        catch (fallbackError) {
+                            rollbackErrors.push(fallbackError);
+                        }
+                    }
+                }
+            }
+            else {
+                const fallbackId = resolveFallbackId(registration);
+                if (fallbackId && fallbackId !== toolId) {
+                    try {
+                        await activateNow(fallbackId, true);
+                    }
+                    catch (fallbackError) {
+                        rollbackErrors.push(fallbackError);
+                    }
+                }
+            }
+            publish();
+            if (rollbackErrors.length === 1)
+                throw error;
+            throw createAggregateError('Editor Tool activation and rollback failed.', rollbackErrors);
+        }
+    };
+    const handleRegistryChange = () => {
+        if (disposed)
+            return;
+        publish();
+        const current = active;
+        if (!current || options.registry.get(current.registration.definition.id) === current.registration)
+            return;
+        void enqueue(async () => {
+            try {
+                if (active !== current)
+                    return;
+                active = null;
+                activationGeneration += 1;
+                let cleanupError;
+                try {
+                    await cleanupRuntime(current, 'unregistered');
+                }
+                catch (error) {
+                    cleanupError = error;
+                }
+                const fallbackId = resolveFallbackId(current.registration);
+                let fallbackError;
+                if (fallbackId) {
+                    try {
+                        await activateNow(fallbackId, true);
+                    }
+                    catch (error) {
+                        fallbackError = error;
+                    }
+                }
+                else
+                    publish();
+                if (cleanupError && fallbackError) {
+                    throw createAggregateError('Editor Tool unload cleanup and fallback failed.', [cleanupError, fallbackError]);
+                }
+                if (cleanupError)
+                    throw cleanupError;
+                if (fallbackError)
+                    throw fallbackError;
+            }
+            catch (error) {
+                backgroundFailure = backgroundFailure
+                    ? createAggregateError('Multiple background Editor Tool operations failed.', [backgroundFailure, error])
+                    : error;
+                publish();
+                throw error;
+            }
+        }).catch(() => { });
+    };
+    const unsubscribeRegistry = options.registry.subscribe(handleRegistryChange);
+    const manager = {
+        snapshot: managerSnapshot,
+        subscribe(listener) {
+            if (disposed)
+                throw new Error('Editor Tool Manager is disposed.');
+            listeners.add(listener);
+            return () => { listeners.delete(listener); };
+        },
+        activate(toolId) {
+            return enqueue(() => activateNow(toolId));
+        },
+        cancel(reason = 'user') {
+            return enqueue(async () => {
+                if (disposed)
+                    return;
+                await active?.runtime.cancel?.(reason);
+            });
+        },
+        rebindContext(nextContext) {
+            return enqueue(async () => {
+                if (disposed || disposeRequested)
+                    throw new Error('Editor Tool Manager is disposed.');
+                const frozen = nextContext ? snapshotEditingContext(nextContext) : null;
+                if (sameContextRevision(context, frozen))
+                    return;
+                const previousContext = context;
+                context = frozen;
+                activationGeneration += 1;
+                const current = active;
+                if (!current) {
+                    publish();
+                    return;
+                }
+                const availability = resolveToolAvailability(current.registration.definition, context);
+                if (!context || availability.state !== 'enabled') {
+                    active = null;
+                    let cleanupError;
+                    try {
+                        await cleanupRuntime(current, 'context-change');
+                    }
+                    catch (error) {
+                        cleanupError = error;
+                    }
+                    const fallbackId = resolveFallbackId(current.registration);
+                    let fallbackError;
+                    if (fallbackId) {
+                        try {
+                            await activateNow(fallbackId);
+                        }
+                        catch (error) {
+                            fallbackError = error;
+                        }
+                    }
+                    else
+                        publish();
+                    if (cleanupError && fallbackError) {
+                        throw createAggregateError('Editing Context cleanup and fallback activation failed.', [cleanupError, fallbackError]);
+                    }
+                    if (cleanupError)
+                        throw cleanupError;
+                    if (fallbackError)
+                        throw fallbackError;
+                    return;
+                }
+                try {
+                    if (current.runtime.rebind)
+                        await current.runtime.rebind(context);
+                    else {
+                        await current.runtime.deactivate?.('context-change');
+                        await current.runtime.activate(context);
+                    }
+                }
+                catch (error) {
+                    context = previousContext;
+                    let rollbackError;
+                    try {
+                        if (!previousContext)
+                            throw new Error('Previous Editing Context is unavailable.');
+                        if (current.runtime.rebind)
+                            await current.runtime.rebind(previousContext);
+                        else
+                            await current.runtime.activate(previousContext);
+                    }
+                    catch (caught) {
+                        rollbackError = caught;
+                        active = null;
+                        try {
+                            await cleanupRuntime(current, 'activation-rollback');
+                        }
+                        catch (cleanupError) {
+                            rollbackError = createAggregateError('Editing Context rollback cleanup failed.', [caught, cleanupError]);
+                        }
+                        const fallbackId = resolveFallbackId(current.registration);
+                        if (fallbackId && fallbackId !== current.registration.definition.id) {
+                            try {
+                                await activateNow(fallbackId, true);
+                            }
+                            catch (fallbackError) {
+                                rollbackError = createAggregateError('Editing Context rollback and fallback failed.', [rollbackError, fallbackError]);
+                            }
+                        }
+                    }
+                    publish();
+                    if (rollbackError) {
+                        throw createAggregateError('Editing Context rebind and rollback failed.', [error, rollbackError]);
+                    }
+                    throw error;
+                }
+                publish();
+            });
+        },
+        whenIdle() {
+            return queue.then(async () => {
+                if (backgroundFailure) {
+                    const error = backgroundFailure;
+                    backgroundFailure = null;
+                    throw error;
+                }
+                if (pendingCleanups.size > 0)
+                    await retryPendingCleanups();
+            });
+        },
+        dispose() {
+            return enqueue(async () => {
+                if (disposed)
+                    return;
+                disposeRequested = true;
+                if (registrySubscribed) {
+                    registrySubscribed = false;
+                    unsubscribeRegistry();
+                }
+                const current = active;
+                const previouslyPending = [...pendingCleanups];
+                active = null;
+                activationGeneration += 1;
+                const cleanupErrors = [];
+                if (current) {
+                    try {
+                        await cleanupRuntime(current, 'manager-dispose');
+                    }
+                    catch (error) {
+                        cleanupErrors.push(error);
+                    }
+                }
+                for (const pending of previouslyPending) {
+                    try {
+                        await cleanupRuntime(pending, pending.cleanup?.reason ?? 'manager-dispose');
+                    }
+                    catch (error) {
+                        cleanupErrors.push(error);
+                    }
+                }
+                if (cleanupErrors.length > 0) {
+                    throw createAggregateError('Editor Tool Manager dispose cleanup failed.', cleanupErrors);
+                }
+                disposed = true;
+                listeners.clear();
+            });
+        },
+    };
+    return Object.freeze(manager);
+}
+export function resolveEditingContextProvider(providers) {
+    const available = providers.filter(provider => provider.canProvide()).sort((left, right) => {
+        const priority = (right.priority ?? 0) - (left.priority ?? 0);
+        return priority || left.id.localeCompare(right.id);
+    });
+    const selected = available[0];
+    if (!selected)
+        throw new Error('No Editing Context provider can provide the current scope.');
+    if (available[1] && (available[1].priority ?? 0) === (selected.priority ?? 0)) {
+        throw new Error(`Ambiguous Editing Context providers at priority ${selected.priority ?? 0}: ${selected.id}, ${available[1].id}`);
+    }
+    return selected;
+}
+export function resolveToolAvailability(definition, context) {
+    if (!context)
+        return Object.freeze({ state: 'disabled', reason: 'No active Editing Context.' });
+    let disabled = null;
+    for (const capabilityId of definition.requiredCapabilities ?? []) {
+        const availability = context.capabilities[capabilityId]
+            ?? Object.freeze({ state: 'hidden', reason: `Capability is unavailable: ${capabilityId}` });
+        if (availability.state === 'hidden')
+            return availability;
+        if (availability.state === 'disabled')
+            disabled ?? (disabled = availability);
+    }
+    return disabled ?? ENABLED;
+}
+export function snapshotEditorToolRegistration(registration) {
+    if (!registration || typeof registration !== 'object') {
+        throw new Error('Editor Tool registration must be an object.');
+    }
+    if (typeof registration.createRuntime !== 'function') {
+        throw new Error('Editor Tool registration requires createRuntime().');
+    }
+    return Object.freeze({
+        definition: snapshotEditorToolDefinition(registration.definition),
+        createRuntime: registration.createRuntime,
+    });
+}
+export function snapshotEditorToolDefinition(definition) {
+    if (!definition || typeof definition !== 'object')
+        throw new Error('Editor Tool definition must be an object.');
+    const id = assertNamespacedId(definition.id, 'Editor Tool id');
+    const label = assertNonEmpty(definition.label, 'Editor Tool label');
+    const group = assertNamespacedId(definition.group, 'Editor Tool group');
+    if (definition.kind !== 'primary' && definition.kind !== 'action') {
+        throw new Error(`Unknown Editor Tool kind: ${String(definition.kind)}`);
+    }
+    const order = definition.order ?? 0;
+    if (!Number.isFinite(order))
+        throw new Error('Editor Tool order must be finite.');
+    const requiredCapabilities = Object.freeze((definition.requiredCapabilities ?? []).map(capability => (assertNamespacedId(capability, 'Editor capability id'))));
+    if (new Set(requiredCapabilities).size !== requiredCapabilities.length) {
+        throw new Error(`Editor Tool required capabilities must be unique: ${id}`);
+    }
+    return Object.freeze({
+        id,
+        label,
+        group,
+        order,
+        kind: definition.kind,
+        requiredCapabilities,
+        ...(definition.icon === undefined ? {} : { icon: assertNonEmpty(definition.icon, 'Editor Tool icon') }),
+        ...(definition.shortcut === undefined ? {} : {
+            shortcut: assertNonEmpty(definition.shortcut, 'Editor Tool shortcut').toUpperCase(),
+        }),
+        ...(definition.fallbackToolId === undefined ? {} : {
+            fallbackToolId: assertNamespacedId(definition.fallbackToolId, 'Editor Tool fallback id'),
+        }),
+    });
+}
+export function snapshotEditingContext(context) {
+    if (!context || typeof context !== 'object')
+        throw new Error('Editing Context snapshot must be an object.');
+    const id = assertNamespacedId(context.id, 'Editing Context id');
+    if (!context.authority || typeof context.authority !== 'object') {
+        throw new Error('Editing Context authority must be an object token.');
+    }
+    if (!Number.isSafeInteger(context.revision) || context.revision < 0) {
+        throw new Error('Editing Context revision must be a non-negative safe integer.');
+    }
+    const capabilities = {};
+    for (const [capabilityId, availability] of Object.entries(context.capabilities ?? {})) {
+        capabilities[assertNamespacedId(capabilityId, 'Editor capability id')] = snapshotAvailability(availability);
+    }
+    return Object.freeze({
+        id,
+        authority: context.authority,
+        revision: context.revision,
+        capabilities: Object.freeze(capabilities),
+        ...(context.metadata ? { metadata: Object.freeze({ ...context.metadata }) } : {}),
+    });
+}
+function createToolPresentation(definition, context, activeToolId) {
+    return Object.freeze({
+        id: definition.id,
+        label: definition.label,
+        group: definition.group,
+        order: definition.order ?? 0,
+        kind: definition.kind,
+        availability: resolveToolAvailability(definition, context),
+        active: activeToolId === definition.id,
+        ...(definition.icon ? { icon: definition.icon } : {}),
+        ...(definition.shortcut ? { shortcut: definition.shortcut } : {}),
+    });
+}
+function snapshotAvailability(value) {
+    if (!value || typeof value !== 'object')
+        throw new Error('Capability availability must be an object.');
+    if (value.state === 'enabled')
+        return ENABLED;
+    if (value.state === 'disabled' || value.state === 'hidden') {
+        return Object.freeze({ state: value.state, reason: assertNonEmpty(value.reason, 'Capability reason') });
+    }
+    throw new Error(`Unknown capability availability state: ${String(value.state)}`);
+}
+function compareToolRegistrations(left, right) {
+    const group = left.definition.group.localeCompare(right.definition.group);
+    if (group)
+        return group;
+    const order = (left.definition.order ?? 0) - (right.definition.order ?? 0);
+    return order || left.definition.id.localeCompare(right.definition.id);
+}
+function sameContextRevision(left, right) {
+    return left === right || (!!left && !!right
+        && left.id === right.id
+        && left.authority === right.authority
+        && left.revision === right.revision);
+}
+function assertEditorToolRuntime(value, id) {
+    if (!value || typeof value !== 'object' || typeof value.activate !== 'function') {
+        throw new Error(`Editor Tool runtime is invalid: ${id}`);
+    }
+}
+function assertNamespacedId(value, label) {
+    const normalized = assertNonEmpty(value, label);
+    if (!/^[a-z0-9]+(?:[._-][a-z0-9]+)+$/.test(normalized)) {
+        throw new Error(`${label} must be namespaced lowercase, got: ${value}`);
+    }
+    return normalized;
+}
+function assertNonEmpty(value, label) {
+    if (typeof value !== 'string' || !value.trim())
+        throw new Error(`${label} must be a non-empty string.`);
+    return value.trim();
+}
+function createAggregateError(message, errors) {
+    const aggregate = new Error(message);
+    aggregate.errors = Object.freeze([...errors]);
+    return aggregate;
+}
+//# sourceMappingURL=editor-tools.js.map