@pwfabric/runtime 0.0.0-stage → 1.0.0-rc.0

package/dist/blocks/index.js

@@ -0,0 +1,24 @@
+/**
+ * @pwfabric/runtime/blocks
+ *
+ * Core UI block schemas, definitions, and React components for the PWFabric platform.
+ *
+ * @module @pwfabric/runtime/blocks
+ */
+// `./blocks/*` directory deleted — first-party block
+// components live exclusively in `pwpack-source/<pack>/blocks/<cat>/<name>/component.tsx`
+// and are loaded at runtime through the dynamic install pipeline.
+export * from './registry.js';
+export * from './composition-rules.js';
+export * from './rule-engine.js';
+export * from './component-types.js';
+export { SurfaceEventContext } from './surface-event-context.js';
+export { SurfaceIdContext } from './surface-id-context.js';
+export { useSurfaceEvents, useSurfaceId } from './hooks.js';
+// canonical test fixture — opt-in for suites that
+// exercise registry-dependent behaviour (BlockRegistry, rule engine,
+// composer prompt, block introspection). Production code must NOT
+// import this; the install pipeline supplies block metadata via
+// `useInstalledAtoms` (browser) / `installedBlocksOverride` (server).
+export { populateTestBlocks, TEST_BLOCK_DEFINITIONS } from './__test-fixtures__/block-fixtures.js';
+//# sourceMappingURL=index.js.map

package/dist/blocks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/blocks/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,qDAAqD;AACrD,0FAA0F;AAC1F,kEAAkE;AAClE,cAAc,eAAe,CAAA;AAC7B,cAAc,wBAAwB,CAAA;AACtC,cAAc,kBAAkB,CAAA;AAChC,cAAc,sBAAsB,CAAA;AACpC,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE3D,kDAAkD;AAClD,qEAAqE;AACrE,kEAAkE;AAClE,gEAAgE;AAChE,sEAAsE;AACtE,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,uCAAuC,CAAA"}

package/dist/blocks/registry.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Block Registry
+ *
+ * CP7: Central registry for block type definitions
+ *
+ * @module @pwfabric/core/blocks/registry
+ */
+import type { BlockDefinition, BlockCategory } from '@pwfabric/core';
+/**
+ * Block Registry
+ *
+ * Manages registration and retrieval of block definitions.
+ */
+export declare class BlockRegistry {
+    private readonly definitions;
+    /**
+     * Register a block definition
+     *
+     * @param definition - Block definition to register
+     * @throws Error if block type already registered
+     */
+    register(definition: BlockDefinition): void;
+    /**
+     * Get a block definition by type
+     *
+     * @param type - Block type identifier
+     * @returns Block definition or undefined
+     */
+    get(type: string): BlockDefinition | undefined;
+    /**
+     * Check if a block type is registered
+     *
+     * @param type - Block type identifier
+     * @returns True if registered
+     */
+    has(type: string): boolean;
+    /**
+     * Get all registered block definitions
+     *
+     * @returns Array of all block definitions
+     */
+    list(): readonly BlockDefinition[];
+    /**
+     * Get block definitions by category
+     *
+     * @param category - Block category
+     * @returns Array of block definitions in category
+     */
+    getByCategory(category: BlockCategory): readonly BlockDefinition[];
+    /**
+     * Get all registered block types
+     *
+     * @returns Array of block type identifiers
+     */
+    types(): readonly string[];
+    /**
+     * Unregister a block definition
+     *
+     * @param type - Block type identifier
+     * @returns True if block was unregistered
+     */
+    unregister(type: string): boolean;
+    /**
+     * Clear all registrations
+     */
+    clear(): void;
+}
+/**
+ * Default block registry singleton (intentionally empty post-).
+ */
+export declare const blockRegistry: BlockRegistry;
+/**
+ * Get the default block registry
+ *
+ * @returns The default block registry instance
+ */
+export declare function getBlockRegistry(): BlockRegistry;
+/**
+ * Create a new block registry
+ *
+ * @param populate - Whether to populate with default blocks
+ * @returns New block registry instance
+ */
+export declare function createBlockRegistry(populate?: boolean): BlockRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/blocks/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/blocks/registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAepE;;;;GAIG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqC;IAEjE;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,eAAe,GAAG,IAAI;IAO3C;;;;;OAKG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAI9C;;;;;OAKG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B;;;;OAIG;IACH,IAAI,IAAI,SAAS,eAAe,EAAE;IAIlC;;;;;OAKG;IACH,aAAa,CAAC,QAAQ,EAAE,aAAa,GAAG,SAAS,eAAe,EAAE;IAIlE;;;;OAIG;IACH,KAAK,IAAI,SAAS,MAAM,EAAE;IAI1B;;;;;OAKG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIjC;;OAEG;IACH,KAAK,IAAI,IAAI;CAGd;AAkBD;;GAEG;AACH,eAAO,MAAM,aAAa,eAA0B,CAAA;AAEpD;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,CAEhD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,UAAQ,GAAG,aAAa,CAKnE"}

package/dist/blocks/registry.js

@@ -0,0 +1,136 @@
+/**
+ * Block Registry
+ *
+ * CP7: Central registry for block type definitions
+ *
+ * @module @pwfabric/core/blocks/registry
+ */
+// legacy first-party `BlockDefinition` imports moved
+// to the `__test-fixtures__/block-fixtures.ts` module so this
+// production registry file no longer pulls the 45 hardcoded blocks
+// into its bundle. Block authoring is canonical in
+// `pwpack-source/<pack>/.../component.tsx`; the runtime registry is
+// populated per world via `getBlockRegistryForWorld` (browser) or
+// `assembleCanonicalRegistry({installedBlocksOverride})` (server).
+// Tests that need a populated singleton must explicitly import
+// `populateTestBlocks` from the fixtures module.
+// ============================================================
+// BLOCK REGISTRY CLASS
+// ============================================================
+/**
+ * Block Registry
+ *
+ * Manages registration and retrieval of block definitions.
+ */
+export class BlockRegistry {
+    definitions = new Map();
+    /**
+     * Register a block definition
+     *
+     * @param definition - Block definition to register
+     * @throws Error if block type already registered
+     */
+    register(definition) {
+        if (this.definitions.has(definition.type)) {
+            throw new Error(`Block type "${definition.type}" is already registered`);
+        }
+        this.definitions.set(definition.type, definition);
+    }
+    /**
+     * Get a block definition by type
+     *
+     * @param type - Block type identifier
+     * @returns Block definition or undefined
+     */
+    get(type) {
+        return this.definitions.get(type);
+    }
+    /**
+     * Check if a block type is registered
+     *
+     * @param type - Block type identifier
+     * @returns True if registered
+     */
+    has(type) {
+        return this.definitions.has(type);
+    }
+    /**
+     * Get all registered block definitions
+     *
+     * @returns Array of all block definitions
+     */
+    list() {
+        return Array.from(this.definitions.values());
+    }
+    /**
+     * Get block definitions by category
+     *
+     * @param category - Block category
+     * @returns Array of block definitions in category
+     */
+    getByCategory(category) {
+        return this.list().filter((def) => def.category === category);
+    }
+    /**
+     * Get all registered block types
+     *
+     * @returns Array of block type identifiers
+     */
+    types() {
+        return Array.from(this.definitions.keys());
+    }
+    /**
+     * Unregister a block definition
+     *
+     * @param type - Block type identifier
+     * @returns True if block was unregistered
+     */
+    unregister(type) {
+        return this.definitions.delete(type);
+    }
+    /**
+     * Clear all registrations
+     */
+    clear() {
+        this.definitions.clear();
+    }
+}
+// ============================================================
+// REGISTRY SINGLETON
+// ============================================================
+/**
+ * the default block registry is empty. Per-world content
+ * comes through the dynamic install pipeline — see
+ * `getBlockRegistryForWorld` (browser) / `loadInstalledBlocksForWorld`
+ * (server). The empty singleton is kept for legacy callers that just
+ * type-check against `BlockRegistry`; production code paths must NOT
+ * depend on it being pre-populated.
+ */
+function createDefaultRegistry() {
+    return new BlockRegistry();
+}
+/**
+ * Default block registry singleton (intentionally empty post-).
+ */
+export const blockRegistry = createDefaultRegistry();
+/**
+ * Get the default block registry
+ *
+ * @returns The default block registry instance
+ */
+export function getBlockRegistry() {
+    return blockRegistry;
+}
+/**
+ * Create a new block registry
+ *
+ * @param populate - Whether to populate with default blocks
+ * @returns New block registry instance
+ */
+export function createBlockRegistry(populate = false) {
+    if (populate) {
+        return createDefaultRegistry();
+    }
+    return new BlockRegistry();
+}
+//# sourceMappingURL=registry.js.map

package/dist/blocks/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/blocks/registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,qDAAqD;AACrD,8DAA8D;AAC9D,mEAAmE;AACnE,mDAAmD;AACnD,oEAAoE;AACpE,kEAAkE;AAClE,mEAAmE;AACnE,+DAA+D;AAC/D,iDAAiD;AAEjD,+DAA+D;AAC/D,uBAAuB;AACvB,+DAA+D;AAE/D;;;;GAIG;AACH,MAAM,OAAO,aAAa;IACP,WAAW,GAAG,IAAI,GAAG,EAA2B,CAAA;IAEjE;;;;;OAKG;IACH,QAAQ,CAAC,UAA2B;QAClC,IAAI,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1C,MAAM,IAAI,KAAK,CAAC,eAAe,UAAU,CAAC,IAAI,yBAAyB,CAAC,CAAA;QAC1E,CAAC;QACD,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE,UAAU,CAAC,CAAA;IACnD,CAAC;IAED;;;;;OAKG;IACH,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IACnC,CAAC;IAED;;;;;OAKG;IACH,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IACnC,CAAC;IAED;;;;OAIG;IACH,IAAI;QACF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC,CAAA;IAC9C,CAAC;IAED;;;;;OAKG;IACH,aAAa,CAAC,QAAuB;QACnC,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAA;IAC/D,CAAC;IAED;;;;OAIG;IACH,KAAK;QACH,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAA;IAC5C,CAAC;IAED;;;;;OAKG;IACH,UAAU,CAAC,IAAY;QACrB,OAAO,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IACtC,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAA;IAC1B,CAAC;CACF;AAED,+DAA+D;AAC/D,qBAAqB;AACrB,+DAA+D;AAE/D;;;;;;;GAOG;AACH,SAAS,qBAAqB;IAC5B,OAAO,IAAI,aAAa,EAAE,CAAA;AAC5B,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,qBAAqB,EAAE,CAAA;AAEpD;;;;GAIG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,aAAa,CAAA;AACtB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAQ,GAAG,KAAK;IAClD,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,qBAAqB,EAAE,CAAA;IAChC,CAAC;IACD,OAAO,IAAI,aAAa,EAAE,CAAA;AAC5B,CAAC"}

package/dist/blocks/rule-engine.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Composition Rule Engine
+ *
+ * CP7: Validation engine for block compositions
+ * Block metadata accessor is now an injectable provider so
+ * web-side editor flows can supply install-aware data without depending on
+ * the populated runtime singleton.
+ *
+ * @module @pwfabric/core/blocks/rule-engine
+ */
+import type { Block, BlockValidationResult as ValidationResult, CompositionRule } from '@pwfabric/core';
+/**
+ * Snapshot of the block metadata the rule engine consults during
+ * validation. A subset of `BlockDefinition` — only the fields that
+ * affect composition decisions (name + child/parent rules).
+ */
+export interface BlockMetaSnapshot {
+    readonly type: string;
+    readonly name: string;
+    readonly canHaveChildren: boolean;
+    readonly allowedChildren?: readonly string[];
+    readonly allowedParents?: readonly string[];
+}
+/**
+ * Pluggable block metadata accessor. The default implementation is a
+ * thin adapter over the legacy `blockRegistry` singleton; install-aware
+ * editor flows construct their own provider that wraps
+ * `useInstalledAtoms` data.
+ */
+export interface BlockMetaProvider {
+    get(type: string): BlockMetaSnapshot | undefined;
+}
+/**
+ * Default provider — reads from the runtime `blockRegistry` singleton.
+ * Returns `undefined` for types absent from the singleton (post-
+ * the singleton is empty by default).
+ */
+export declare const defaultBlockMetaProvider: BlockMetaProvider;
+export declare const CompositionErrorCode: {
+    readonly MAX_DEPTH_EXCEEDED: "MAX_DEPTH_EXCEEDED";
+    readonly INVALID_CHILD: "INVALID_CHILD";
+    readonly INVALID_PARENT: "INVALID_PARENT";
+    readonly NO_CHILDREN_ALLOWED: "NO_CHILDREN_ALLOWED";
+    readonly SELF_NESTING: "SELF_NESTING";
+    readonly UNKNOWN_BLOCK_TYPE: "UNKNOWN_BLOCK_TYPE";
+    readonly ORPHANED_BLOCK: "ORPHANED_BLOCK";
+};
+export type CompositionErrorCodeType = (typeof CompositionErrorCode)[keyof typeof CompositionErrorCode];
+/**
+ * Composition Rule Engine
+ *
+ * Validates block compositions against defined rules.
+ */
+export declare class CompositionRuleEngine {
+    /** Rules for this engine instance (reserved for future custom rule support) */
+    readonly rules: readonly CompositionRule[];
+    /** Block metadata accessor */
+    readonly meta: BlockMetaProvider;
+    constructor(rules?: readonly CompositionRule[], meta?: BlockMetaProvider);
+    /**
+     * Check if a child can be inserted into a parent
+     *
+     * @param parent - Parent block (null for root level)
+     * @param childType - Type of child block to insert
+     * @param currentDepth - Current nesting depth
+     * @returns Validation result
+     */
+    canInsert(parent: Block | null, childType: string, currentDepth?: number): ValidationResult;
+    /**
+     * Check if a block can be moved to a new parent
+     *
+     * @param block - Block to move
+     * @param newParent - New parent block (null for root level)
+     * @param currentDepth - Current nesting depth
+     * @returns Validation result
+     */
+    canMove(block: Block, newParent: Block | null, currentDepth?: number): ValidationResult;
+    /**
+     * Validate an entire block tree
+     *
+     * @param blocks - Root level blocks to validate
+     * @returns Array of validation errors
+     */
+    validateTree(blocks: readonly Block[]): ValidationResult;
+    /**
+     * Get the depth of a block in a tree
+     *
+     * @param blocks - Root level blocks
+     * @param targetId - ID of block to find
+     * @returns Depth of block or -1 if not found
+     */
+    getBlockDepth(blocks: readonly Block[], targetId: string): number;
+    /**
+     * Check if a block is a descendant of another block
+     *
+     * @param block - Block to check descendants of
+     * @param potentialAncestor - Potential ancestor block
+     * @returns True if block is a descendant
+     */
+    private isDescendantOf;
+}
+/**
+ * Default composition rule engine singleton
+ */
+export declare const compositionRuleEngine: CompositionRuleEngine;
+/**
+ * Get the default composition rule engine
+ *
+ * @returns The default rule engine instance
+ */
+export declare function getCompositionRuleEngine(): CompositionRuleEngine;
+/**
+ * Create a new composition rule engine
+ *
+ * @param rules - Optional custom rules
+ * @param meta - Optional block metadata provider
+ * @returns New rule engine instance
+ */
+export declare function createCompositionRuleEngine(rules?: readonly CompositionRule[], meta?: BlockMetaProvider): CompositionRuleEngine;
+/**
+ * Check if a block can be inserted (convenience function)
+ */
+export declare function canInsertBlock(parent: Block | null, childType: string, currentDepth?: number): ValidationResult;
+/**
+ * Check if a block can be moved (convenience function)
+ */
+export declare function canMoveBlock(block: Block, newParent: Block | null, currentDepth?: number): ValidationResult;
+/**
+ * Validate a block tree (convenience function)
+ */
+export declare function validateBlockTree(blocks: readonly Block[]): ValidationResult;
+//# sourceMappingURL=rule-engine.d.ts.map

package/dist/blocks/rule-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-engine.d.ts","sourceRoot":"","sources":["../../src/blocks/rule-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,KAAK,EACL,qBAAqB,IAAI,gBAAgB,EAEzC,eAAe,EAEhB,MAAM,gBAAgB,CAAA;AASvB;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAA;IACjC,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5C,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC5C;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAAA;CACjD;AAYD;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,iBAKtC,CAAA;AAMD,eAAO,MAAM,oBAAoB;;;;;;;;CAQvB,CAAA;AAEV,MAAM,MAAM,wBAAwB,GAClC,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,OAAO,oBAAoB,CAAC,CAAA;AAMlE;;;;GAIG;AACH,qBAAa,qBAAqB;IAChC,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,CAAA;IAC1C,8BAA8B;IAC9B,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;gBAG9B,KAAK,GAAE,SAAS,eAAe,EAAqB,EACpD,IAAI,GAAE,iBAA4C;IAMpD;;;;;;;OAOG;IACH,SAAS,CAAC,MAAM,EAAE,KAAK,GAAG,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,SAAI,GAAG,gBAAgB;IAyFtF;;;;;;;OAOG;IACH,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,GAAG,IAAI,EAAE,YAAY,SAAI,GAAG,gBAAgB;IAkBlF;;;;;OAKG;IACH,YAAY,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,GAAG,gBAAgB;IA0DxD;;;;;;OAMG;IACH,aAAa,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IAiBjE;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;CAevB;AAMD;;GAEG;AACH,eAAO,MAAM,qBAAqB,uBAA8B,CAAA;AAEhE;;;;GAIG;AACH,wBAAgB,wBAAwB,IAAI,qBAAqB,CAEhE;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,CAAC,EAAE,SAAS,eAAe,EAAE,EAClC,IAAI,CAAC,EAAE,iBAAiB,GACvB,qBAAqB,CAEvB;AAMD;;GAEG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,KAAK,GAAG,IAAI,EACpB,SAAS,EAAE,MAAM,EACjB,YAAY,SAAI,GACf,gBAAgB,CAElB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,KAAK,EACZ,SAAS,EAAE,KAAK,GAAG,IAAI,EACvB,YAAY,SAAI,GACf,gBAAgB,CAElB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,GAAG,gBAAgB,CAE5E"}