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

package/dist/blocks/composition-rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"composition-rules.js","sourceRoot":"","sources":["../../src/blocks/composition-rules.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Composition Rules\n *\n * CP7: Rules defining valid block compositions\n *\n * @module @pwfabric/core/blocks/composition-rules\n */\n\nimport type { CompositionRule } from '@pwfabric/core'\nimport { MAX_NESTING_DEPTH } from '@pwfabric/core'\n\n// ============================================================\n// BUILT-IN RULES\n// ============================================================\n\n/**\n * Maximum nesting depth rule\n *\n * Prevents blocks from being nested too deeply.\n */\nexport const maxDepthRule: CompositionRule = {\n  type: 'max_depth',\n  description: `Blocks cannot be nested more than ${MAX_NESTING_DEPTH} levels deep`,\n  appliesTo: '*',\n  config: {\n    maxDepth: MAX_NESTING_DEPTH,\n  },\n}\n\n/**\n * Form children rule\n *\n * Forms can contain all form input elements plus structural/content blocks.\n */\nexport const formChildrenRule: CompositionRule = {\n  type: 'allowed_children',\n  description:\n    'Forms can contain form input elements and structural/content blocks (text, heading, container, divider, button)',\n  appliesTo: 'form',\n  config: {\n    allowedChildren: [\n      // Form input elements — the form family of the first-party base pack as\n      // shipped, so every field a form pattern uses passes validation.\n      'input',\n      'textarea',\n      'select',\n      'checkbox',\n      'radio',\n      'toggle',\n      'slider',\n      'combobox',\n      'date-input',\n      'file-dropzone',\n      'number-stepper',\n      'otp-input',\n      'rich-text-editor',\n      'segmented-control',\n      'tag-input',\n      // legacy names kept so older documents keep validating\n      'switch',\n      'file-upload',\n      // Structural / content blocks valid inside forms\n      'button',\n      'text',\n      'heading',\n      'container',\n      'divider',\n      'badge',\n      'icon',\n      'link',\n      'alert',\n    ],\n  },\n}\n\n/**\n * Grid children rule\n *\n * Grids cannot have nested grids as direct children.\n */\nexport const gridChildrenRule: CompositionRule = {\n  type: 'allowed_children',\n  description: 'Grids cannot contain other grids as direct children',\n  appliesTo: 'grid',\n  config: {\n    disallowedChildren: ['grid'],\n  },\n}\n\n/**\n * Button no children rule\n *\n * Buttons cannot have children.\n */\nexport const buttonNoChildrenRule: CompositionRule = {\n  type: 'no_children',\n  description: 'Buttons cannot have children',\n  appliesTo: 'button',\n  config: {},\n}\n\n/**\n * Text no children rule\n *\n * Text blocks cannot have children.\n */\nexport const textNoChildrenRule: CompositionRule = {\n  type: 'no_children',\n  description: 'Text blocks cannot have children',\n  appliesTo: 'text',\n  config: {},\n}\n\n/**\n * Heading no children rule\n *\n * Heading blocks cannot have children.\n */\nexport const headingNoChildrenRule: CompositionRule = {\n  type: 'no_children',\n  description: 'Heading blocks cannot have children',\n  appliesTo: 'heading',\n  config: {},\n}\n\n/**\n * Image no children rule\n *\n * Image blocks cannot have children.\n */\nexport const imageNoChildrenRule: CompositionRule = {\n  type: 'no_children',\n  description: 'Image blocks cannot have children',\n  appliesTo: 'image',\n  config: {},\n}\n\n/**\n * Input no children rule\n *\n * Input blocks cannot have children.\n */\nexport const inputNoChildrenRule: CompositionRule = {\n  type: 'no_children',\n  description: 'Input blocks cannot have children',\n  appliesTo: 'input',\n  config: {},\n}\n\n/**\n * Input required parent rule\n *\n * Inputs should be inside forms or containers.\n */\nexport const inputParentRule: CompositionRule = {\n  type: 'allowed_parents',\n  description: 'Inputs should be placed inside forms or containers',\n  appliesTo: 'input',\n  config: {\n    allowedParents: ['form', 'container'],\n    severity: 'warning',\n  },\n}\n\n/**\n * Link no children rule\n *\n * Link blocks cannot have children.\n */\nexport const linkNoChildrenRule: CompositionRule = {\n  type: 'no_children',\n  description: 'Link blocks cannot have children',\n  appliesTo: 'link',\n  config: {},\n}\n\n/**\n * Icon no children rule\n *\n * Icon blocks cannot have children.\n */\nexport const iconNoChildrenRule: CompositionRule = {\n  type: 'no_children',\n  description: 'Icon blocks cannot have children',\n  appliesTo: 'icon',\n  config: {},\n}\n\n/**\n * Badge no children rule\n *\n * Badge blocks cannot have children.\n */\nexport const badgeNoChildrenRule: CompositionRule = {\n  type: 'no_children',\n  description: 'Badge blocks cannot have children',\n  appliesTo: 'badge',\n  config: {},\n}\n\n/**\n * Code no children rule\n *\n * Code blocks cannot have children.\n */\nexport const codeNoChildrenRule: CompositionRule = {\n  type: 'no_children',\n  description: 'Code blocks cannot have children',\n  appliesTo: 'code',\n  config: {},\n}\n\n/**\n * Divider no children rule\n *\n * Divider blocks cannot have children.\n */\nexport const dividerNoChildrenRule: CompositionRule = {\n  type: 'no_children',\n  description: 'Divider blocks cannot have children',\n  appliesTo: 'divider',\n  config: {},\n}\n\n/**\n * List no children rule\n *\n * List blocks cannot have children.\n */\nexport const listNoChildrenRule: CompositionRule = {\n  type: 'no_children',\n  description: 'List blocks cannot have children',\n  appliesTo: 'list',\n  config: {},\n}\n\n/**\n * Table no children rule\n *\n * Table blocks cannot have children.\n */\nexport const tableNoChildrenRule: CompositionRule = {\n  type: 'no_children',\n  description: 'Table blocks cannot have children',\n  appliesTo: 'table',\n  config: {},\n}\n\n// ============================================================\n// INTERACTIVE BLOCK RULES\n// ============================================================\n\n/**\n * Accordion no children rule\n *\n * Accordion items are defined via props, not children.\n */\nexport const accordionNoChildrenRule: CompositionRule = {\n  type: 'no_children',\n  description: 'Accordion items are defined via props, not as children blocks',\n  appliesTo: 'accordion',\n  config: {},\n}\n\n/**\n * Dropdown no children rule\n *\n * Dropdown items are defined via props, not children.\n */\nexport const dropdownNoChildrenRule: CompositionRule = {\n  type: 'no_children',\n  description: 'Dropdown items are defined via props, not as children blocks',\n  appliesTo: 'dropdown',\n  config: {},\n}\n\n/**\n * Avatar no children rule\n *\n * Avatar is a leaf block with no children.\n */\nexport const avatarNoChildrenRule: CompositionRule = {\n  type: 'no_children',\n  description: 'Avatar blocks cannot have children',\n  appliesTo: 'avatar',\n  config: {},\n}\n\n/**\n * Tooltip children rule\n *\n * Tooltip can wrap specific inline/interactive blocks.\n */\nexport const tooltipChildrenRule: CompositionRule = {\n  type: 'allowed_children',\n  description: 'Tooltips can only wrap text, buttons, icons, badges, and links',\n  appliesTo: 'tooltip',\n  config: {\n    allowedChildren: ['text', 'button', 'icon', 'badge', 'link'],\n  },\n}\n\n/**\n * Tabs children rule\n *\n * Tabs can contain containers as tab panels.\n */\nexport const tabsChildrenRule: CompositionRule = {\n  type: 'allowed_children',\n  description: 'Tabs can only contain containers as tab panel content',\n  appliesTo: 'tabs',\n  config: {\n    allowedChildren: ['container'],\n  },\n}\n\n/**\n * Modal children rule\n *\n * Modal can contain layout and content blocks.\n */\nexport const modalChildrenRule: CompositionRule = {\n  type: 'allowed_children',\n  description: 'Modals can contain layout and content blocks',\n  appliesTo: 'modal',\n  config: {\n    allowedChildren: [\n      'container',\n      'grid',\n      'text',\n      'heading',\n      'button',\n      'image',\n      'form',\n      'input',\n      'list',\n      'table',\n      'divider',\n      'icon',\n      'badge',\n    ],\n  },\n}\n\n/**\n * No self nesting rule\n *\n * Blocks cannot be nested inside themselves.\n */\nexport const noSelfNestingRule: CompositionRule = {\n  type: 'no_self_nesting',\n  description: 'Blocks cannot be nested inside themselves',\n  appliesTo: '*',\n  config: {},\n}\n\n// ============================================================\n// ALL RULES\n// ============================================================\n\n/**\n * All composition rules\n */\nexport const compositionRules: readonly CompositionRule[] = [\n  maxDepthRule,\n  formChildrenRule,\n  gridChildrenRule,\n  // Content blocks - no children\n  buttonNoChildrenRule,\n  textNoChildrenRule,\n  headingNoChildrenRule,\n  linkNoChildrenRule,\n  iconNoChildrenRule,\n  badgeNoChildrenRule,\n  codeNoChildrenRule,\n  dividerNoChildrenRule,\n  // Layout blocks - no children (leaf)\n  listNoChildrenRule,\n  tableNoChildrenRule,\n  // Media blocks - no children\n  imageNoChildrenRule,\n  // Form blocks - no children\n  inputNoChildrenRule,\n  inputParentRule,\n  // Interactive blocks\n  accordionNoChildrenRule,\n  dropdownNoChildrenRule,\n  avatarNoChildrenRule,\n  tooltipChildrenRule,\n  tabsChildrenRule,\n  modalChildrenRule,\n  // Universal rules\n  noSelfNestingRule,\n] as const\n\n/**\n * Get rules that apply to a specific block type\n *\n * @param blockType - Block type to get rules for\n * @returns Array of applicable rules\n */\nexport function getRulesForBlockType(blockType: string): readonly CompositionRule[] {\n  return compositionRules.filter((rule) => rule.appliesTo === '*' || rule.appliesTo === blockType)\n}\n\n/**\n * Get rules by type\n *\n * @param ruleType - Rule type to filter by\n * @returns Array of matching rules\n */\nexport function getRulesByType(ruleType: CompositionRule['type']): readonly CompositionRule[] {\n  return compositionRules.filter((rule) => rule.type === ruleType)\n}\n\n// ============================================================\n// CANONICAL CHILD SETS (single source of truth)\n// Import these in API validator instead of redeclaring.\n// ============================================================\n\n/** Allowed direct children of a tabs block */\nexport const TABS_ALLOWED_CHILDREN = new Set(tabsChildrenRule.config.allowedChildren as string[])\n\n/** Allowed direct children of a form block */\nexport const FORM_ALLOWED_CHILDREN = new Set(formChildrenRule.config.allowedChildren as string[])\n"]}

package/dist/blocks/hooks.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Block Component Hooks
+ *
+ * React hooks used by block components for event emission and surface ID access.
+ *
+ * @module @pwfabric/runtime/blocks/hooks
+ */
+import type { SurfaceEventDescriptor } from '@pwfabric/contracts';
+/**
+ * Hook for block components to emit surface events.
+ *
+ * When the context is absent (no bus provided by the surface renderer)
+ * the hook returns a no-op `emit` so callers need no guard code.
+ *
+ * @example
+ * ```tsx
+ * const { emit } = useSurfaceEvents()
+ *
+ * const handleClick = () => {
+ *   emit({ type: SURFACE_EVENTS.BLOCK_CLICK, surfaceId, blockId: block.id })
+ * }
+ * ```
+ */
+export declare function useSurfaceEvents(): {
+    emit: (partial: Omit<SurfaceEventDescriptor, 'timestamp'>) => void;
+};
+/**
+ * Hook that returns the current surface ID from `SurfaceIdContext`.
+ * Returns an empty string when no `BehaviorSurfaceProvider` is in the tree.
+ */
+export declare function useSurfaceId(): string;

package/dist/blocks/hooks.js

@@ -0,0 +1,42 @@
+/**
+ * Block Component Hooks
+ *
+ * React hooks used by block components for event emission and surface ID access.
+ *
+ * @module @pwfabric/runtime/blocks/hooks
+ */
+import { useContext } from 'react';
+import { SurfaceEventContext } from './surface-event-context.js';
+import { SurfaceIdContext } from './surface-id-context.js';
+/**
+ * Hook for block components to emit surface events.
+ *
+ * When the context is absent (no bus provided by the surface renderer)
+ * the hook returns a no-op `emit` so callers need no guard code.
+ *
+ * @example
+ * ```tsx
+ * const { emit } = useSurfaceEvents()
+ *
+ * const handleClick = () => {
+ *   emit({ type: SURFACE_EVENTS.BLOCK_CLICK, surfaceId, blockId: block.id })
+ * }
+ * ```
+ */
+export function useSurfaceEvents() {
+    const bus = useContext(SurfaceEventContext);
+    const emit = (partial) => {
+        if (!bus)
+            return;
+        bus.emit({ ...partial, timestamp: Date.now() });
+    };
+    return { emit };
+}
+/**
+ * Hook that returns the current surface ID from `SurfaceIdContext`.
+ * Returns an empty string when no `BehaviorSurfaceProvider` is in the tree.
+ */
+export function useSurfaceId() {
+    return useContext(SurfaceIdContext);
+}
+//# sourceMappingURL=hooks.js.map

package/dist/blocks/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../src/blocks/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,OAAO,CAAA;AAElC,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAE1D;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,gBAAgB;IAG9B,MAAM,GAAG,GAAG,UAAU,CAAC,mBAAmB,CAAC,CAAA;IAE3C,MAAM,IAAI,GAAG,CAAC,OAAkD,EAAQ,EAAE;QACxE,IAAI,CAAC,GAAG;YAAE,OAAM;QAChB,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAA;IACjD,CAAC,CAAA;IAED,OAAO,EAAE,IAAI,EAAE,CAAA;AACjB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY;IAC1B,OAAO,UAAU,CAAC,gBAAgB,CAAC,CAAA;AACrC,CAAC","sourcesContent":["/**\n * Block Component Hooks\n *\n * React hooks used by block components for event emission and surface ID access.\n *\n * @module @pwfabric/runtime/blocks/hooks\n */\n\nimport { useContext } from 'react'\nimport type { SurfaceEventDescriptor } from '@pwfabric/contracts'\nimport { SurfaceEventContext } from './surface-event-context.js'\nimport { SurfaceIdContext } from './surface-id-context.js'\n\n/**\n * Hook for block components to emit surface events.\n *\n * When the context is absent (no bus provided by the surface renderer)\n * the hook returns a no-op `emit` so callers need no guard code.\n *\n * @example\n * ```tsx\n * const { emit } = useSurfaceEvents()\n *\n * const handleClick = () => {\n *   emit({ type: SURFACE_EVENTS.BLOCK_CLICK, surfaceId, blockId: block.id })\n * }\n * ```\n */\nexport function useSurfaceEvents(): {\n  emit: (partial: Omit<SurfaceEventDescriptor, 'timestamp'>) => void\n} {\n  const bus = useContext(SurfaceEventContext)\n\n  const emit = (partial: Omit<SurfaceEventDescriptor, 'timestamp'>): void => {\n    if (!bus) return\n    bus.emit({ ...partial, timestamp: Date.now() })\n  }\n\n  return { emit }\n}\n\n/**\n * Hook that returns the current surface ID from `SurfaceIdContext`.\n * Returns an empty string when no `BehaviorSurfaceProvider` is in the tree.\n */\nexport function useSurfaceId(): string {\n  return useContext(SurfaceIdContext)\n}\n"]}

package/dist/blocks/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @pwfabric/runtime/blocks
+ *
+ * Core UI block schemas, definitions, and React components for the PWFabric platform.
+ *
+ * @module @pwfabric/runtime/blocks
+ */
+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';

package/dist/blocks/index.js

@@ -0,0 +1,23 @@
+/**
+ * @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';
+// The test fixtures (populateTestBlocks, TEST_BLOCK_DEFINITIONS) are NOT
+// exported: tests import ./__test-fixtures__/block-fixtures.js directly, and
+// the published package does not ship that folder. Block metadata reaches a
+// running app through the install pipeline (`useInstalledAtoms` in the
+// browser, `installedBlocksOverride` on the server).
+//# 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,yEAAyE;AACzE,6EAA6E;AAC7E,4EAA4E;AAC5E,uEAAuE;AACvE,qDAAqD","sourcesContent":["/**\n * @pwfabric/runtime/blocks\n *\n * Core UI block schemas, definitions, and React components for the PWFabric platform.\n *\n * @module @pwfabric/runtime/blocks\n */\n\n// `./blocks/*` directory deleted — first-party block\n// components live exclusively in `pwpack-source/<pack>/blocks/<cat>/<name>/component.tsx`\n// and are loaded at runtime through the dynamic install pipeline.\nexport * from './registry.js'\nexport * from './composition-rules.js'\nexport * from './rule-engine.js'\nexport * from './component-types.js'\nexport { SurfaceEventContext } from './surface-event-context.js'\nexport { SurfaceIdContext } from './surface-id-context.js'\nexport { useSurfaceEvents, useSurfaceId } from './hooks.js'\n\n// The test fixtures (populateTestBlocks, TEST_BLOCK_DEFINITIONS) are NOT\n// exported: tests import ./__test-fixtures__/block-fixtures.js directly, and\n// the published package does not ship that folder. Block metadata reaches a\n// running app through the install pipeline (`useInstalledAtoms` in the\n// browser, `installedBlocksOverride` on the server).\n"]}

package/dist/blocks/registry.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 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;

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

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

@@ -0,0 +1,131 @@
+/**
+ * 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;