@grafloria/element 0.3.20 → 0.3.21

package/src/libs/renderer/src/ext/extension-host.d.ts

@@ -1,144 +0,0 @@
-/**
- * ============================================================================
- * Card 0 — the ExtensionHost, and Card 7 — the capability-scoped sandbox
- * ============================================================================
- *
- * Before Wave 6 the extension story was seven unrelated registries, reached by
- * importing whatever module happened to own them:
- *
- *   registerShape / registerPathShape        (renderer, module-global map)
- *   registerLinkTemplate / registerLabelTemplate / registerMarker
- *                                            (renderer, module-global maps)
- *   RoutingEngine.registerRouter             (engine, per-engine instance)
- *   TemplateRegistry.register                (engine, per-engine instance)
- *   CustomAnimationRegistry.register         (renderer, global singleton)
- *   PropertyEditorRegistryService            (ANGULAR-only — see note below)
- *   HandleRegistryService                    (ANGULAR-only)
- *
- * Not one of them returned a disposer, three had no removal path at all, and two
- * were reachable only from Angular. There was no way to answer "what did this
- * plugin add?" or "unload it".
- *
- * The ExtensionHost is the ONE public seam over those. It is a FACADE — it does
- * not reimplement a single registry — and it adds exactly what they lacked:
- *
- *   • ONE entry point, `host.register(extension)`.
- *   • LEAST PRIVILEGE. An extension declares `capabilities: ['shapes']` and
- *     receives an object with ONLY `shapes` on it. There is no `engine` handle,
- *     no `document`, no way to reach a registry it did not ask for. Asking for a
- *     capability the host was not given (e.g. `routers` with no engine bound)
- *     fails AT REGISTRATION, not at first use.
- *   • DISPOSERS EVERYWHERE. Every registration is tracked; `dispose()` unwinds
- *     the extension completely and RESTORES anything it overrode.
- *   • ENGINE COMPAT. A manifest declares the engine range it supports and is
- *     REJECTED — loudly — if it does not match.
- *   • LAZY LOADING. `registerLazy()` takes a `() => Promise<Extension>` and does
- *     not touch it until `activate(id)`.
- *
- * ---------------------------------------------------------------------------
- * NOTE — the two Angular-only registries
- * ---------------------------------------------------------------------------
- * `PropertyEditorRegistryService` and `HandleRegistryService` are Angular
- * `@Injectable`s living in `libs/renderer-angular`. `libs/renderer` may not
- * import Angular (hard rule), so they CANNOT be wrapped from here without first
- * being lowered into the framework-free core. That lowering is a real piece of
- * work and is NOT in this wave — stated plainly rather than faked with an
- * any-typed shim. The host is designed for it: adding `editors` / `handles` to
- * `CapabilityName` is additive and breaks nothing.
- */
-import type { DiagramEngine } from '@grafloria/engine';
-import type { CapabilityName, ExtensionContext, HostBindings } from './capabilities';
-import type { Disposer } from './disposable';
-import type { ExtensionManifest } from './manifest';
-/** The engine/host API version extensions declare compatibility against. */
-export declare const EXTENSION_API_VERSION = "1.0.0";
-/**
- * An extension. `activate` receives ONLY the capabilities its manifest declared.
- *
- * ```ts
- * const starPlugin: Extension<'shapes'> = {
- *   manifest: {
- *     id: 'acme.stars',
- *     version: '1.2.0',
- *     engines: { grafloria: '^1.0.0' },
- *     capabilities: ['shapes'],
- *   },
- *   activate({ capabilities }) {
- *     // `capabilities.routers` does not exist here — not typed, not present.
- *     capabilities.shapes.registerPath('star', starPath);
- *   },
- * };
- * host.register(starPlugin);
- * ```
- */
-export interface Extension<C extends CapabilityName = CapabilityName> {
-    manifest: ExtensionManifest<C>;
-    /**
-     * Set up. Anything you register is tracked and undone on dispose; you may also
-     * return a disposer (or push onto `context.onDispose`) for your own resources.
-     */
-    activate(context: ExtensionContext<C>): void | Disposer | Promise<void | Disposer>;
-    /** Optional explicit teardown, run before the tracked disposers. */
-    deactivate?(): void;
-}
-/** A lazily-loaded extension: nothing is imported until `activate(id)`. */
-export type LazyExtension<C extends CapabilityName = CapabilityName> = () => Promise<Extension<C> | {
-    default: Extension<C>;
-}>;
-export interface RegisteredExtension {
-    readonly manifest: ExtensionManifest;
-    readonly active: boolean;
-    /** Registrations this extension currently holds. */
-    readonly registrationCount: number;
-}
-export interface ExtensionHostOptions extends HostBindings {
-    /** Reject manifests whose `engines.grafloria` range excludes this. */
-    apiVersion?: string;
-}
-export declare class ExtensionHost {
-    private readonly entries;
-    private readonly bindings;
-    private readonly apiVersion;
-    private disposed;
-    constructor(options: ExtensionHostOptions);
-    /** The engine this host is bound to (hosts, not extensions, may ask). */
-    get engine(): DiagramEngine;
-    /**
-     * Register and ACTIVATE an extension.
-     *
-     * Throws — deliberately, and before any side effect — when the manifest is
-     * malformed, the id is taken, the engine range excludes this host, or the
-     * extension asks for a capability this host cannot grant. A plugin that half-
-     * loads is worse than one that refuses to.
-     */
-    register<C extends CapabilityName>(extension: Extension<C>): Disposer;
-    /**
-     * Register WITHOUT loading. The factory is not called until `activate(id)`,
-     * so a 500 KB plugin costs nothing until something needs it.
-     *
-     * The manifest is supplied up front precisely so the host can answer "what
-     * shapes/routers exist?" and validate compatibility WITHOUT paying the import.
-     */
-    registerLazy<C extends CapabilityName>(manifest: ExtensionManifest<C>, load: LazyExtension<C>): Disposer;
-    /** Activate a lazily-registered extension (imports it on first call). */
-    activate(id: string): Promise<void>;
-    private activateEntry;
-    /** Tear one extension down. Every registration it made is undone. */
-    dispose(id: string): void;
-    /** Tear everything down. The host is unusable afterwards. */
-    disposeAll(): void;
-    has(id: string): boolean;
-    get(id: string): RegisteredExtension | undefined;
-    /** Everything registered, loaded or not. */
-    list(): RegisteredExtension[];
-    private assertLive;
-    private assertIdFree;
-    /**
-     * Least privilege, enforced EARLY. An extension that declares `panels` in a
-     * headless host (no DOM bound) is rejected here — not at first `createPanel()`
-     * call three minutes into a session.
-     */
-    private assertGrantable;
-}
-/** Convenience: a host bound to a live `createDiagram()` instance. */
-export declare function createExtensionHost(options: ExtensionHostOptions): ExtensionHost;

package/src/libs/renderer/src/ext/extension-host.js

@@ -1,272 +0,0 @@
-"use strict";
-/**
- * ============================================================================
- * Card 0 — the ExtensionHost, and Card 7 — the capability-scoped sandbox
- * ============================================================================
- *
- * Before Wave 6 the extension story was seven unrelated registries, reached by
- * importing whatever module happened to own them:
- *
- *   registerShape / registerPathShape        (renderer, module-global map)
- *   registerLinkTemplate / registerLabelTemplate / registerMarker
- *                                            (renderer, module-global maps)
- *   RoutingEngine.registerRouter             (engine, per-engine instance)
- *   TemplateRegistry.register                (engine, per-engine instance)
- *   CustomAnimationRegistry.register         (renderer, global singleton)
- *   PropertyEditorRegistryService            (ANGULAR-only — see note below)
- *   HandleRegistryService                    (ANGULAR-only)
- *
- * Not one of them returned a disposer, three had no removal path at all, and two
- * were reachable only from Angular. There was no way to answer "what did this
- * plugin add?" or "unload it".
- *
- * The ExtensionHost is the ONE public seam over those. It is a FACADE — it does
- * not reimplement a single registry — and it adds exactly what they lacked:
- *
- *   • ONE entry point, `host.register(extension)`.
- *   • LEAST PRIVILEGE. An extension declares `capabilities: ['shapes']` and
- *     receives an object with ONLY `shapes` on it. There is no `engine` handle,
- *     no `document`, no way to reach a registry it did not ask for. Asking for a
- *     capability the host was not given (e.g. `routers` with no engine bound)
- *     fails AT REGISTRATION, not at first use.
- *   • DISPOSERS EVERYWHERE. Every registration is tracked; `dispose()` unwinds
- *     the extension completely and RESTORES anything it overrode.
- *   • ENGINE COMPAT. A manifest declares the engine range it supports and is
- *     REJECTED — loudly — if it does not match.
- *   • LAZY LOADING. `registerLazy()` takes a `() => Promise<Extension>` and does
- *     not touch it until `activate(id)`.
- *
- * ---------------------------------------------------------------------------
- * NOTE — the two Angular-only registries
- * ---------------------------------------------------------------------------
- * `PropertyEditorRegistryService` and `HandleRegistryService` are Angular
- * `@Injectable`s living in `libs/renderer-angular`. `libs/renderer` may not
- * import Angular (hard rule), so they CANNOT be wrapped from here without first
- * being lowered into the framework-free core. That lowering is a real piece of
- * work and is NOT in this wave — stated plainly rather than faked with an
- * any-typed shim. The host is designed for it: adding `editors` / `handles` to
- * `CapabilityName` is additive and breaks nothing.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ExtensionHost = exports.EXTENSION_API_VERSION = void 0;
-exports.createExtensionHost = createExtensionHost;
-const tslib_1 = require("tslib");
-const disposable_1 = require("./disposable");
-const capability_factory_1 = require("./capability-factory");
-const manifest_1 = require("./manifest");
-/** The engine/host API version extensions declare compatibility against. */
-exports.EXTENSION_API_VERSION = '1.0.0';
-class ExtensionHost {
-    constructor(options) {
-        var _a;
-        this.entries = new Map();
-        this.disposed = false;
-        this.bindings = options;
-        this.apiVersion = (_a = options.apiVersion) !== null && _a !== void 0 ? _a : exports.EXTENSION_API_VERSION;
-    }
-    /** The engine this host is bound to (hosts, not extensions, may ask). */
-    get engine() {
-        return this.bindings.engine;
-    }
-    /**
-     * Register and ACTIVATE an extension.
-     *
-     * Throws — deliberately, and before any side effect — when the manifest is
-     * malformed, the id is taken, the engine range excludes this host, or the
-     * extension asks for a capability this host cannot grant. A plugin that half-
-     * loads is worse than one that refuses to.
-     */
-    register(extension) {
-        this.assertLive();
-        const manifest = extension.manifest;
-        (0, manifest_1.validateManifest)(manifest);
-        (0, manifest_1.assertEngineCompatible)(manifest, this.apiVersion);
-        this.assertIdFree(manifest.id);
-        this.assertGrantable(manifest);
-        const entry = {
-            manifest: manifest,
-            extension: extension,
-            store: new disposable_1.DisposableStore(),
-            active: false,
-        };
-        this.entries.set(manifest.id, entry);
-        try {
-            this.activateEntry(entry);
-        }
-        catch (error) {
-            // Roll back anything the failed activate() managed to register, so a
-            // broken plugin cannot leave shrapnel in the registries.
-            entry.store.dispose();
-            this.entries.delete(manifest.id);
-            throw error;
-        }
-        return () => this.dispose(manifest.id);
-    }
-    /**
-     * Register WITHOUT loading. The factory is not called until `activate(id)`,
-     * so a 500 KB plugin costs nothing until something needs it.
-     *
-     * The manifest is supplied up front precisely so the host can answer "what
-     * shapes/routers exist?" and validate compatibility WITHOUT paying the import.
-     */
-    registerLazy(manifest, load) {
-        this.assertLive();
-        (0, manifest_1.validateManifest)(manifest);
-        (0, manifest_1.assertEngineCompatible)(manifest, this.apiVersion);
-        this.assertIdFree(manifest.id);
-        this.assertGrantable(manifest);
-        this.entries.set(manifest.id, {
-            manifest: manifest,
-            lazy: load,
-            store: new disposable_1.DisposableStore(),
-            active: false,
-        });
-        return () => this.dispose(manifest.id);
-    }
-    /** Activate a lazily-registered extension (imports it on first call). */
-    activate(id) {
-        return tslib_1.__awaiter(this, void 0, void 0, function* () {
-            var _a;
-            this.assertLive();
-            const entry = this.entries.get(id);
-            if (!entry)
-                throw new Error(`[ExtensionHost] unknown extension '${id}'`);
-            if (entry.active)
-                return;
-            if (!entry.extension && entry.lazy) {
-                const loaded = yield entry.lazy();
-                const resolved = (_a = loaded.default) !== null && _a !== void 0 ? _a : loaded;
-                entry.extension = resolved;
-                // The lazily-loaded module could ship a manifest that disagrees with the
-                // one we validated. Trust the DECLARED one (we gated on it) and refuse the
-                // mismatch rather than silently widening the extension's privileges.
-                const actual = entry.extension.manifest;
-                if (actual && actual.id !== entry.manifest.id) {
-                    throw new Error(`[ExtensionHost] lazy extension '${entry.manifest.id}' loaded a manifest for ` +
-                        `'${actual.id}' — refusing (a plugin may not change its identity on load)`);
-                }
-            }
-            if (!entry.extension) {
-                throw new Error(`[ExtensionHost] extension '${id}' has no implementation`);
-            }
-            try {
-                yield this.activateEntry(entry);
-            }
-            catch (error) {
-                entry.store.dispose();
-                throw error;
-            }
-        });
-    }
-    activateEntry(entry) {
-        const extension = entry.extension;
-        if (!extension)
-            return;
-        const capabilities = (0, capability_factory_1.buildCapabilities)(entry.manifest.capabilities, this.bindings, entry.store);
-        const context = {
-            id: entry.manifest.id,
-            capabilities: capabilities,
-            onDispose: (disposer) => {
-                entry.store.add(disposer);
-            },
-        };
-        const result = extension.activate(context);
-        const finish = (returned) => {
-            var _a, _b;
-            if (typeof returned === 'function')
-                entry.store.add(returned);
-            entry.active = true;
-            // A contributed shape/connector changes the picture, so ask for a repaint.
-            (_b = (_a = this.bindings).requestRender) === null || _b === void 0 ? void 0 : _b.call(_a);
-        };
-        if (result && typeof result.then === 'function') {
-            return result.then(finish);
-        }
-        finish(result);
-    }
-    /** Tear one extension down. Every registration it made is undone. */
-    dispose(id) {
-        var _a, _b, _c, _d;
-        const entry = this.entries.get(id);
-        if (!entry)
-            return;
-        this.entries.delete(id);
-        try {
-            if (entry.active)
-                (_b = (_a = entry.extension) === null || _a === void 0 ? void 0 : _a.deactivate) === null || _b === void 0 ? void 0 : _b.call(_a);
-        }
-        finally {
-            // Even if deactivate() throws, the registrations MUST come out.
-            entry.store.dispose();
-            entry.active = false;
-            (_d = (_c = this.bindings).requestRender) === null || _d === void 0 ? void 0 : _d.call(_c);
-        }
-    }
-    /** Tear everything down. The host is unusable afterwards. */
-    disposeAll() {
-        if (this.disposed)
-            return;
-        for (const id of [...this.entries.keys()])
-            this.dispose(id);
-        this.disposed = true;
-    }
-    has(id) {
-        return this.entries.has(id);
-    }
-    get(id) {
-        const entry = this.entries.get(id);
-        if (!entry)
-            return undefined;
-        return {
-            manifest: entry.manifest,
-            active: entry.active,
-            registrationCount: entry.store.size,
-        };
-    }
-    /** Everything registered, loaded or not. */
-    list() {
-        return [...this.entries.values()].map((entry) => ({
-            manifest: entry.manifest,
-            active: entry.active,
-            registrationCount: entry.store.size,
-        }));
-    }
-    // -- guards ---------------------------------------------------------------
-    assertLive() {
-        if (this.disposed)
-            throw new Error('[ExtensionHost] host has been disposed');
-    }
-    assertIdFree(id) {
-        if (this.entries.has(id)) {
-            throw new Error(`[ExtensionHost] extension '${id}' is already registered`);
-        }
-    }
-    /**
-     * Least privilege, enforced EARLY. An extension that declares `panels` in a
-     * headless host (no DOM bound) is rejected here — not at first `createPanel()`
-     * call three minutes into a session.
-     */
-    assertGrantable(manifest) {
-        for (const capability of manifest.capabilities) {
-            if (capability === 'panels' && !this.bindings.root) {
-                throw new Error(`[ExtensionHost] extension '${manifest.id}' declares the 'panels' capability, ` +
-                    `but this host has no DOM root bound (headless). Refusing to register.`);
-            }
-            if (capability === 'routers' && !this.bindings.engine) {
-                throw new Error(`[ExtensionHost] extension '${manifest.id}' declares 'routers', but this ` +
-                    `host has no engine bound. Refusing to register.`);
-            }
-            if (capability === 'templates' && !this.bindings.templateRegistry) {
-                throw new Error(`[ExtensionHost] extension '${manifest.id}' declares 'templates', but this host ` +
-                    `has no TemplateRegistry bound. Pass one as \`templateRegistry\` — the engine ` +
-                    `does not expose it, so the host cannot find it for you.`);
-            }
-        }
-    }
-}
-exports.ExtensionHost = ExtensionHost;
-/** Convenience: a host bound to a live `createDiagram()` instance. */
-function createExtensionHost(options) {
-    return new ExtensionHost(options);
-}
-//# sourceMappingURL=extension-host.js.map

package/src/libs/renderer/src/ext/index.d.ts

@@ -1,62 +0,0 @@
-/**
- * ============================================================================
- * @grafloria/renderer — the EXTENSION API (Wave 6)
- * ============================================================================
- *
- * The public, semver'd seam for everything a host can add to the engine. One
- * entry point, typed capability grants, and a disposer on every registration.
- *
- * ```ts
- * import { createDiagram, createExtensionHost, attachCanvasPlugins } from '@grafloria/renderer';
- *
- * const diagram = createDiagram(el, { nodes, edges });
- *
- * // The drop-in components (Card 6) — background grid, minimap, controls.
- * const plugins = attachCanvasPlugins(diagram, {
- *   background: { variant: 'dots', gap: 20 },
- *   minimap: true,
- *   controls: true,
- * });
- *
- * // A capability-scoped extension (Cards 0 + 7).
- * const host = createExtensionHost({
- *   engine: diagram.getEngine(),
- *   root: diagram.container,
- *   requestRender: () => diagram.render(),
- * });
- *
- * host.register({
- *   manifest: {
- *     id: 'acme.stars',
- *     version: '1.0.0',
- *     engines: { grafloria: '^1.0.0' },
- *     capabilities: ['shapes', 'links'],   // ← the ENFORCED grant
- *     contributes: { shapes: ['star'], connectors: ['zigzag'] },
- *   },
- *   activate({ capabilities }) {
- *     capabilities.shapes.registerPath('star', starPath);
- *     capabilities.links.registerConnector('zigzag', ({ points }) => zigzag(points));
- *     // capabilities.routers is NOT here — the manifest did not ask for it.
- *   },
- * });
- * ```
- *
- * Everything above is undone by `host.dispose('acme.stars')` — including shapes
- * that OVERRODE a built-in, which are restored rather than deleted.
- */
-export * from './extension-host';
-export * from './capabilities';
-export * from './disposable';
-export * from './registry-scope';
-export * from './diagram-registry';
-export * from './manifest';
-export * from './link-pipeline';
-export * from './tools';
-export * from './public-api';
-export * from './node-component';
-export * from './portal';
-export * from './components/background';
-export * from './components/minimap';
-export * from './components/controls';
-export * from './components/attach';
-export { loadCanvasPlugins } from './plugins-loader';

package/src/libs/renderer/src/ext/index.js

@@ -1,91 +0,0 @@
-"use strict";
-/**
- * ============================================================================
- * @grafloria/renderer — the EXTENSION API (Wave 6)
- * ============================================================================
- *
- * The public, semver'd seam for everything a host can add to the engine. One
- * entry point, typed capability grants, and a disposer on every registration.
- *
- * ```ts
- * import { createDiagram, createExtensionHost, attachCanvasPlugins } from '@grafloria/renderer';
- *
- * const diagram = createDiagram(el, { nodes, edges });
- *
- * // The drop-in components (Card 6) — background grid, minimap, controls.
- * const plugins = attachCanvasPlugins(diagram, {
- *   background: { variant: 'dots', gap: 20 },
- *   minimap: true,
- *   controls: true,
- * });
- *
- * // A capability-scoped extension (Cards 0 + 7).
- * const host = createExtensionHost({
- *   engine: diagram.getEngine(),
- *   root: diagram.container,
- *   requestRender: () => diagram.render(),
- * });
- *
- * host.register({
- *   manifest: {
- *     id: 'acme.stars',
- *     version: '1.0.0',
- *     engines: { grafloria: '^1.0.0' },
- *     capabilities: ['shapes', 'links'],   // ← the ENFORCED grant
- *     contributes: { shapes: ['star'], connectors: ['zigzag'] },
- *   },
- *   activate({ capabilities }) {
- *     capabilities.shapes.registerPath('star', starPath);
- *     capabilities.links.registerConnector('zigzag', ({ points }) => zigzag(points));
- *     // capabilities.routers is NOT here — the manifest did not ask for it.
- *   },
- * });
- * ```
- *
- * Everything above is undone by `host.dispose('acme.stars')` — including shapes
- * that OVERRODE a built-in, which are restored rather than deleted.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadCanvasPlugins = void 0;
-const tslib_1 = require("tslib");
-// Card 0 — the host + the typed capability contract.
-tslib_1.__exportStar(require("./extension-host"), exports);
-tslib_1.__exportStar(require("./capabilities"), exports);
-tslib_1.__exportStar(require("./disposable"), exports);
-// PER-DIAGRAM REGISTRIES. The contribution registries used to be module-scope
-// Maps — one process, one vocabulary — so two diagrams on one page could not
-// disagree about what a shape name meant, and one diagram's extension teardown
-// stripped the other's registration. `diagram.registry` is one diagram's own
-// table; the module-level `registerShape()` / `defineStyle()` / … are still the
-// process-wide one, and a diagram falls through to it for every name it did not
-// claim itself.
-tslib_1.__exportStar(require("./registry-scope"), exports);
-tslib_1.__exportStar(require("./diagram-registry"), exports);
-// Card 7 — the manifest, the compat gate, and the semver matcher behind it.
-tslib_1.__exportStar(require("./manifest"), exports);
-// Card 2 — the link-pipeline seams that were missing (anchors, connection
-// points, connectors). The router half already existed on the RoutingEngine.
-tslib_1.__exportStar(require("./link-pipeline"), exports);
-// Card 5 — the tool registry + the isValidConnection hook.
-tslib_1.__exportStar(require("./tools"), exports);
-// Card 4 — the documented public reactive + imperative surface over the
-// ViewportController / InteractionController / createDiagram machinery waves 3-4
-// already shipped. A named API, not a new engine.
-tslib_1.__exportStar(require("./public-api"), exports);
-// Card 3 — the framework-agnostic node-component authoring contract (typed
-// props, lifecycle, MEASURED SIZE) on top of wave 4's renderCustomNode hook.
-tslib_1.__exportStar(require("./node-component"), exports);
-// Card 6 — portals (screen space + world space) and the drop-in components.
-tslib_1.__exportStar(require("./portal"), exports);
-tslib_1.__exportStar(require("./components/background"), exports);
-tslib_1.__exportStar(require("./components/minimap"), exports);
-tslib_1.__exportStar(require("./components/controls"), exports);
-tslib_1.__exportStar(require("./components/attach"), exports);
-// NOTE: `capability-factory` is deliberately NOT exported. It is the host's
-// private wiring to the real registries; an extension reaching it directly would
-// bypass the capability grant, which is the whole point of Card 7.
-// Lazy entry for the plugin chain — what the framework wrappers use, so
-// consumers who never mount plugins ship none of this chain.
-var plugins_loader_1 = require("./plugins-loader");
-Object.defineProperty(exports, "loadCanvasPlugins", { enumerable: true, get: function () { return plugins_loader_1.loadCanvasPlugins; } });
-//# sourceMappingURL=index.js.map