@wp-typia/project-tools 0.22.2 → 0.22.4

package/dist/runtime/built-in-block-code-templates/interactivity.d.ts

@@ -1,6 +1,6 @@
 export declare const INTERACTIVITY_EDIT_TEMPLATE = "import type { BlockEditProps } from '@wp-typia/block-types/blocks/registration';\nimport { __ } from '@wordpress/i18n';\nimport { useBlockProps, InspectorControls, RichText, BlockControls, AlignmentToolbar } from '@wordpress/block-editor';\nimport { PanelBody, RangeControl, Button, Notice } from '@wordpress/components';\nimport { useState } from '@wordpress/element';\nimport currentManifest from './manifest-document';\nimport { {{slugCamelCase}}Store } from './interactivity-store';\nimport {\n  InspectorFromManifest,\n  useEditorFields,\n  useTypedAttributeUpdater,\n} from '@wp-typia/block-runtime/inspector';\nimport type { {{pascalCase}}Attributes } from './types';\nimport {\n  sanitize{{pascalCase}}Attributes,\n  validate{{pascalCase}}Attributes,\n} from './validators';\nimport { useTypiaValidation } from './hooks';\n\ntype EditProps = BlockEditProps<{{pascalCase}}Attributes>;\n\nconst actionButtonRowStyle = { display: 'flex', gap: '8px', marginTop: '16px' };\nconst validationListStyle = { margin: 0, paddingLeft: '1em' };\n\nexport default function Edit({ attributes, setAttributes, isSelected }: EditProps) {\n  const [isPreviewing, setIsPreviewing] = useState(false);\n  const editorFields = useEditorFields(currentManifest, {\n    manual: ['content', 'clickCount', 'maxClicks'],\n    labels: {\n      alignment: __('Alignment', '{{textDomain}}'),\n      animation: __('Animation', '{{textDomain}}'),\n      interactiveMode: __('Interactive Mode', '{{textDomain}}'),\n      isVisible: __('Visible', '{{textDomain}}'),\n      showCounter: __('Show Counter', '{{textDomain}}'),\n    },\n  });\n  const { errorMessages, isValid } = useTypiaValidation(\n    attributes,\n    validate{{pascalCase}}Attributes,\n  );\n  const validateEditorUpdate = (nextAttributes: {{pascalCase}}Attributes) => {\n    try {\n      return {\n        data: sanitize{{pascalCase}}Attributes(nextAttributes),\n        errors: [],\n        isValid: true as const,\n      };\n    } catch {\n      return validate{{pascalCase}}Attributes(nextAttributes);\n    }\n  };\n  const { updateField } = useTypedAttributeUpdater(\n    attributes,\n    setAttributes,\n    validateEditorUpdate\n  );\n  const alignmentValue = editorFields.getStringValue(\n    attributes,\n    'alignment',\n    'left'\n  ) as NonNullable<{{pascalCase}}Attributes['alignment']>;\n  const clickCount = attributes.clickCount ?? 0;\n  const isVisible = editorFields.getBooleanValue(\n    attributes,\n    'isVisible',\n    true\n  );\n  const isAnimating = attributes.isAnimating ?? false;\n  const maxClicks = attributes.maxClicks ?? 0;\n  const showCounter = editorFields.getBooleanValue(\n    attributes,\n    'showCounter',\n    true\n  );\n  const interactiveMode = editorFields.getStringValue(\n    attributes,\n    'interactiveMode',\n    'click'\n  ) as NonNullable<{{pascalCase}}Attributes['interactiveMode']>;\n  const animation = editorFields.getStringValue(\n    attributes,\n    'animation',\n    'none'\n  ) as NonNullable<{{pascalCase}}Attributes['animation']>;\n\n  const blockProps = useBlockProps({\n    className: `{{cssClassName}} {{cssClassName}}--${interactiveMode}`,\n    'data-wp-interactive': {{slugCamelCase}}Store.directive.interactive,\n    'data-wp-context': JSON.stringify(\n      {{slugCamelCase}}Store.createContext({\n        clicks: clickCount,\n        isAnimating,\n        isVisible,\n        animation,\n        maxClicks,\n      })\n    )\n  });\n  const previewContentStyle = { textAlign: alignmentValue };\n  const progressBarStyle = { width: `${(clickCount / maxClicks) * 100}%` };\n  const clicksDirective = {{slugCamelCase}}Store.directive.state('clicks');\n  const isAnimatingDirective = {{slugCamelCase}}Store.directive.state('isAnimating');\n  const progressDirective = {{slugCamelCase}}Store.directive.state('progress') + \" + '%'\";\n\n  const resetCounter = () => {\n    updateField('clickCount', 0);\n    updateField('isAnimating', false);\n  };\n\n  const testAnimation = () => {\n    updateField('isAnimating', true);\n    setTimeout(() => {\n      updateField('isAnimating', false);\n    }, 1000);\n  };\n\n  return (\n    <>\n      <BlockControls>\n        <AlignmentToolbar\n          value={alignmentValue}\n          onChange={(value) => updateField('alignment', (value || alignmentValue) as NonNullable<{{pascalCase}}Attributes['alignment']>)}\n        />\n      </BlockControls>\n\n      <InspectorControls>\n        <InspectorFromManifest\n          attributes={attributes}\n          fieldLookup={editorFields}\n          onChange={updateField}\n          paths={['alignment', 'interactiveMode', 'animation', 'showCounter', 'isVisible']}\n          title={__('Interactive Settings', '{{textDomain}}')}\n        />\n\n        <PanelBody title={__('Counter Settings', '{{textDomain}}')}>\n          <RangeControl\n            label={__('Max Clicks', '{{textDomain}}')}\n            value={maxClicks}\n            onChange={(value) => updateField('maxClicks', value ?? maxClicks)}\n            min={0}\n            max={100}\n            help={__('Set to 0 for unlimited clicks', '{{textDomain}}')}\n          />\n\n          <div style={actionButtonRowStyle}>\n            <Button\n              variant=\"secondary\"\n              onClick={resetCounter}\n              isSmall\n            >\n              {__('Reset Counter', '{{textDomain}}')}\n            </Button>\n            <Button\n              variant=\"secondary\"\n              onClick={testAnimation}\n              isSmall\n            >\n              {__('Test Animation', '{{textDomain}}')}\n            </Button>\n          </div>\n        </PanelBody>\n\n        {!isValid && (\n          <PanelBody title={__('Validation Errors', '{{textDomain}}')} initialOpen>\n            {errorMessages.map((error, index) => (\n              <Notice key={index} status=\"error\" isDismissible={false}>\n                {error}\n              </Notice>\n            ))}\n          </PanelBody>\n        )}\n\n        {isSelected && (\n          <PanelBody title={__('Preview', '{{textDomain}}')}>\n            <Button\n              variant={isPreviewing ? 'primary' : 'secondary'}\n              onClick={() => setIsPreviewing(!isPreviewing)}\n              aria-pressed={isPreviewing}\n              isSmall\n            >\n              {isPreviewing\n                ? __('Disable Preview Mode', '{{textDomain}}')\n                : __('Enable Preview Mode', '{{textDomain}}')}\n            </Button>\n\n            {clickCount > 0 && (\n              <Notice status=\"info\" isDismissible={false}>\n                {__('Current clicks:', '{{textDomain}}')} {clickCount}\n                {maxClicks > 0 && ` / ${maxClicks}`}\n              </Notice>\n            )}\n          </PanelBody>\n        )}\n      </InspectorControls>\n\n      <div {...blockProps}>\n        <div\n          className={`{{cssClassName}}__content ${isAnimating ? 'is-animating' : ''}`}\n          style={previewContentStyle}\n          data-wp-on--click={isPreviewing ? {{slugCamelCase}}Store.directive.action('handleClick') : undefined}\n          data-wp-on--mouseenter={isPreviewing && interactiveMode === 'hover' ? {{slugCamelCase}}Store.directive.action('handleMouseEnter') : undefined}\n          data-wp-on--mouseleave={isPreviewing && interactiveMode === 'hover' ? {{slugCamelCase}}Store.directive.action('handleMouseLeave') : undefined}\n        >\n          <RichText\n            tagName=\"p\"\n            value={attributes.content}\n            onChange={(value) => updateField('content', value)}\n            placeholder={__( {{titleJson}} + ' \u2013 click me to interact!', '{{textDomain}}')}\n          />\n\n          {!isValid && (\n            <Notice status=\"error\" isDismissible={false}>\n              <p>\n                <strong>{__('Validation Errors', '{{textDomain}}')}</strong>\n              </p>\n              <ul style={validationListStyle}>\n                {errorMessages.map((error, index) => (\n                  <li key={index}>{error}</li>\n                ))}\n              </ul>\n            </Notice>\n          )}\n\n          {showCounter && (\n            <div className=\"{{cssClassName}}__counter\">\n              <span className=\"{{cssClassName}}__counter-label\">\n                {__('Clicks:', '{{textDomain}}')}\n              </span>\n              <span\n                className=\"{{cssClassName}}__counter-value\"\n                data-wp-text={clicksDirective}\n              >\n                {clickCount}\n              </span>\n            </div>\n          )}\n\n          {maxClicks > 0 && (\n            <div className=\"{{cssClassName}}__progress\">\n              <div\n                className=\"{{cssClassName}}__progress-bar\"\n                style={progressBarStyle}\n                data-wp-style--width={progressDirective}\n              />\n            </div>\n          )}\n\n          {animation !== 'none' && (\n            <div\n              className={`{{cssClassName}}__animation ${isAnimating ? 'is-active' : ''}`}\n              data-wp-class--is-active={isAnimatingDirective}\n            >\n              {animation}\n            </div>\n          )}\n        </div>\n      </div>\n    </>\n  );\n}\n";
 export declare const INTERACTIVITY_SAVE_TEMPLATE = "import { useBlockProps, RichText } from '@wordpress/block-editor';\nimport { __ } from '@wordpress/i18n';\nimport { {{slugCamelCase}}Store } from './interactivity-store';\nimport type { {{pascalCase}}Attributes } from './types';\n\nexport default function Save({ attributes }: { attributes: {{pascalCase}}Attributes }) {\n  const clickCount = attributes.clickCount ?? 0;\n  const interactiveMode = attributes.interactiveMode ?? 'click';\n  const animation = attributes.animation ?? 'none';\n  const isAnimating = attributes.isAnimating ?? false;\n  const isVisible = attributes.isVisible ?? true;\n  const maxClicks = attributes.maxClicks ?? 0;\n  const showCounter = attributes.showCounter ?? true;\n  const contentStyle = { textAlign: attributes.alignment };\n  const clickActionDirective = {{slugCamelCase}}Store.directive.action('handleClick');\n  const visibilityHiddenDirective = {{slugCamelCase}}Store.directive.negate(\n    {{slugCamelCase}}Store.directive.state('isVisible')\n  );\n  const clicksDirective = {{slugCamelCase}}Store.directive.state('clicks');\n  const clampedClicksDirective = {{slugCamelCase}}Store.directive.state('clampedClicks');\n  const isAnimatingDirective = {{slugCamelCase}}Store.directive.state('isAnimating');\n  const completionHiddenDirective = {{slugCamelCase}}Store.directive.negate(\n    {{slugCamelCase}}Store.directive.state('isComplete')\n  );\n  const resetActionDirective = {{slugCamelCase}}Store.directive.action('reset');\n  const blockProps = useBlockProps.save({\n    className: `{{cssClassName}} {{cssClassName}}--${interactiveMode}`,\n    'data-wp-interactive': {{slugCamelCase}}Store.directive.interactive,\n    'data-wp-context': JSON.stringify(\n      {{slugCamelCase}}Store.createContext({\n        clicks: clickCount,\n        isAnimating,\n        isVisible,\n        animation,\n        maxClicks,\n      })\n    )\n  });\n  const progressDirective = {{slugCamelCase}}Store.directive.state('progress') + \" + '%'\";\n\n  return (\n    <div {...blockProps}>\n      <div\n        className={`{{cssClassName}}__content ${isAnimating ? 'is-animating' : ''}`}\n        style={contentStyle}\n        data-wp-on--click={clickActionDirective}\n        data-wp-on--mouseenter={interactiveMode === 'hover' ? {{slugCamelCase}}Store.directive.action('handleMouseEnter') : undefined}\n        data-wp-on--mouseleave={interactiveMode === 'hover' ? {{slugCamelCase}}Store.directive.action('handleMouseLeave') : undefined}\n        data-wp-bind--hidden={visibilityHiddenDirective}\n      >\n        <RichText.Content\n          tagName=\"p\"\n          value={attributes.content}\n          className=\"{{cssClassName}}__text\"\n        />\n\n        {showCounter && (\n          <div\n            className=\"{{cssClassName}}__counter\"\n            role=\"status\"\n            aria-live=\"polite\"\n            aria-atomic=\"true\"\n          >\n            <span className=\"{{cssClassName}}__counter-label\">\n              { __( 'Clicks:', '{{textDomain}}' ) }\n            </span>\n            <span\n              className=\"{{cssClassName}}__counter-value\"\n              data-wp-text={clicksDirective}\n            >\n              {clickCount}\n            </span>\n          </div>\n        )}\n\n        {maxClicks > 0 && (\n          <div className=\"{{cssClassName}}__progress\">\n            <div\n              className=\"{{cssClassName}}__progress-bar\"\n              role=\"progressbar\"\n              aria-label={ __( 'Click progress', '{{textDomain}}' ) }\n              aria-valuemin={0}\n              aria-valuemax={maxClicks}\n              aria-valuenow={Math.min(clickCount, maxClicks)}\n              data-wp-bind--aria-valuenow={clampedClicksDirective}\n              data-wp-style--width={progressDirective}\n            />\n          </div>\n        )}\n\n        <div\n          className={`{{cssClassName}}__animation ${animation}`}\n          aria-hidden=\"true\"\n          data-wp-class--is-active={isAnimatingDirective}\n        />\n\n        {maxClicks > 0 && (\n          <div\n            className=\"{{cssClassName}}__completion\"\n            role=\"status\"\n            aria-live=\"polite\"\n            aria-atomic=\"true\"\n            data-wp-bind--hidden={completionHiddenDirective}\n          >\n            { __( '\uD83C\uDF89 Complete!', '{{textDomain}}' ) }\n          </div>\n        )}\n\n        <button\n          className=\"{{cssClassName}}__reset\"\n          data-wp-on--click={resetActionDirective}\n          aria-label={ __( 'Reset counter', '{{textDomain}}' ) }\n        >\n          <span aria-hidden=\"true\">\u21BB</span>\n          <span className=\"screen-reader-text\">\n            { __( 'Reset counter', '{{textDomain}}' ) }\n          </span>\n        </button>\n      </div>\n    </div>\n  );\n}\n";
 export declare const INTERACTIVITY_INDEX_TEMPLATE = "import {\n  registerScaffoldBlockType,\n  type BlockConfiguration,\n} from '@wp-typia/block-types/blocks/registration';\nimport type { BlockSupports } from '@wp-typia/block-types/blocks/supports';\nimport {\n  buildScaffoldBlockRegistration,\n  parseScaffoldBlockMetadata,\n} from '@wp-typia/block-runtime/blocks';\n\nimport Edit from './edit';\nimport Save from './save';\nimport metadata from './block-metadata';\nimport './editor.scss';\nimport './style.scss';\n\nimport type { {{pascalCase}}Attributes } from './types';\n\nconst scaffoldSupports = {\n  html: false,\n  align: true,\n  anchor: true,\n  className: true,\n  interactivity: true,\n} satisfies BlockSupports;\n\nconst registration = buildScaffoldBlockRegistration(\n  parseScaffoldBlockMetadata<BlockConfiguration<{{pascalCase}}Attributes>>(metadata),\n  {\n    supports: scaffoldSupports,\n    edit: Edit,\n    save: Save,\n  }\n);\n\nregisterScaffoldBlockType(registration.name, registration.settings);\n";
-export declare const INTERACTIVITY_STORE_TEMPLATE = "import type {\n  {{pascalCase}}Context,\n  {{pascalCase}}State,\n} from './types';\n\ntype InteractivityActionShape = object;\ntype InteractivityCallbackShape = object;\ntype InteractivityContextShape = object;\ntype InteractivityStateShape = object;\ntype InteractivityCallable = CallableFunction;\ntype InteractivityKey<T extends object> = Extract<keyof T, string>;\ntype InteractivityMethodKey<T extends object> = {\n  [Key in InteractivityKey<T>]: T[Key] extends InteractivityCallable ? Key : never;\n}[InteractivityKey<T>];\n\ntype InteractivityDirectivePath<\n  Root extends string,\n  Key extends string,\n> = `${Root}.${Key}`;\n\ntype NegatedInteractivityDirectivePath<Path extends string> = `!${Path}`;\n\nexport interface TypedInteractivityDirectiveHelpers<\n  State extends InteractivityStateShape,\n  Context extends InteractivityContextShape,\n  Actions extends InteractivityActionShape,\n  Callbacks extends InteractivityCallbackShape,\n  Namespace extends string,\n> {\n  readonly interactive: Namespace;\n  action<Key extends InteractivityMethodKey<Actions>>(\n    key: Key,\n  ): InteractivityDirectivePath<'actions', Key>;\n  callback<Key extends InteractivityMethodKey<Callbacks>>(\n    key: Key,\n  ): InteractivityDirectivePath<'callbacks', Key>;\n  state<Key extends InteractivityKey<State>>(\n    key: Key,\n  ): InteractivityDirectivePath<'state', Key>;\n  context<Key extends InteractivityKey<Context>>(\n    key: Key,\n  ): InteractivityDirectivePath<'context', Key>;\n  negate<Path extends string>(\n    path: Path,\n  ): NegatedInteractivityDirectivePath<Path>;\n}\n\nexport interface TypedInteractivityStore<\n  Namespace extends string,\n  State extends InteractivityStateShape,\n  Context extends InteractivityContextShape,\n  Actions extends InteractivityActionShape,\n  Callbacks extends InteractivityCallbackShape,\n> {\n  readonly namespace: Namespace;\n  readonly state: State;\n  readonly context: Context;\n  readonly actions: Actions;\n  readonly callbacks: Callbacks;\n  readonly directive: TypedInteractivityDirectiveHelpers<\n    State,\n    Context,\n    Actions,\n    Callbacks,\n    Namespace\n  >;\n  createContext(value: Context): Context;\n}\n\nexport function defineInteractivityStore<\n  Namespace extends string,\n  State extends InteractivityStateShape,\n  Context extends InteractivityContextShape,\n  Actions extends InteractivityActionShape,\n  Callbacks extends InteractivityCallbackShape,\n>(config: {\n  readonly namespace: Namespace;\n  readonly state: State;\n  readonly context: Context;\n  readonly actions: Actions;\n  readonly callbacks: Callbacks;\n}): TypedInteractivityStore<Namespace, State, Context, Actions, Callbacks> {\n  return {\n    namespace: config.namespace,\n    state: config.state,\n    context: config.context,\n    actions: config.actions,\n    callbacks: config.callbacks,\n    directive: {\n      interactive: config.namespace,\n      action<Key extends InteractivityMethodKey<Actions>>(key: Key) {\n        return `actions.${key}` as InteractivityDirectivePath<'actions', Key>;\n      },\n      callback<Key extends InteractivityMethodKey<Callbacks>>(key: Key) {\n        return `callbacks.${key}` as InteractivityDirectivePath<'callbacks', Key>;\n      },\n      state<Key extends InteractivityKey<State>>(key: Key) {\n        return `state.${key}` as InteractivityDirectivePath<'state', Key>;\n      },\n      context<Key extends InteractivityKey<Context>>(key: Key) {\n        return `context.${key}` as InteractivityDirectivePath<'context', Key>;\n      },\n      negate<Path extends string>(path: Path) {\n        return `!${path}` as NegatedInteractivityDirectivePath<Path>;\n      },\n    },\n    createContext(value) {\n      return value;\n    },\n  };\n}\n\ntype InteractivityActionHandler = CallableFunction;\n\nexport interface {{pascalCase}}StoreActions {\n  handleClick: InteractivityActionHandler;\n  handleMouseEnter: InteractivityActionHandler;\n  handleMouseLeave: InteractivityActionHandler;\n  reset: InteractivityActionHandler;\n}\n\nexport interface {{pascalCase}}StoreCallbacks {}\n\nexport const {{slugCamelCase}}Store = defineInteractivityStore({\n  namespace: '{{slugKebabCase}}',\n  state: {} as {{pascalCase}}State,\n  context: {} as {{pascalCase}}Context,\n  actions: {} as {{pascalCase}}StoreActions,\n  callbacks: {} as {{pascalCase}}StoreCallbacks,\n});\n";
+export declare const INTERACTIVITY_STORE_TEMPLATE = "import type {\n  {{pascalCase}}Context,\n  {{pascalCase}}State,\n} from './types';\n\ntype InteractivityActionShape = object;\ntype InteractivityCallbackShape = object;\ntype InteractivityContextShape = object;\ntype InteractivityStateShape = object;\ntype InteractivityCallable =\n  | ((...args: unknown[]) => unknown)\n  | ReturnType<typeof import('@wordpress/interactivity').withSyncEvent>;\ntype InteractivityKey<T extends object> = Extract<keyof T, string>;\ntype InteractivityMethodKey<T extends object> = {\n  [Key in InteractivityKey<T>]: T[Key] extends InteractivityCallable ? Key : never;\n}[InteractivityKey<T>];\n\ntype InteractivityDirectivePath<\n  Root extends string,\n  Key extends string,\n> = `${Root}.${Key}`;\n\ntype NegatedInteractivityDirectivePath<Path extends string> = `!${Path}`;\n\nexport interface TypedInteractivityDirectiveHelpers<\n  State extends InteractivityStateShape,\n  Context extends InteractivityContextShape,\n  Actions extends InteractivityActionShape,\n  Callbacks extends InteractivityCallbackShape,\n  Namespace extends string,\n> {\n  readonly interactive: Namespace;\n  action<Key extends InteractivityMethodKey<Actions>>(\n    key: Key,\n  ): InteractivityDirectivePath<'actions', Key>;\n  callback<Key extends InteractivityMethodKey<Callbacks>>(\n    key: Key,\n  ): InteractivityDirectivePath<'callbacks', Key>;\n  state<Key extends InteractivityKey<State>>(\n    key: Key,\n  ): InteractivityDirectivePath<'state', Key>;\n  context<Key extends InteractivityKey<Context>>(\n    key: Key,\n  ): InteractivityDirectivePath<'context', Key>;\n  negate<Path extends string>(\n    path: Path,\n  ): NegatedInteractivityDirectivePath<Path>;\n}\n\nexport interface TypedInteractivityStore<\n  Namespace extends string,\n  State extends InteractivityStateShape,\n  Context extends InteractivityContextShape,\n  Actions extends InteractivityActionShape,\n  Callbacks extends InteractivityCallbackShape,\n> {\n  readonly namespace: Namespace;\n  readonly state: State;\n  readonly context: Context;\n  readonly actions: Actions;\n  readonly callbacks: Callbacks;\n  readonly directive: TypedInteractivityDirectiveHelpers<\n    State,\n    Context,\n    Actions,\n    Callbacks,\n    Namespace\n  >;\n  createContext(value: Context): Context;\n}\n\nexport function defineInteractivityStore<\n  Namespace extends string,\n  State extends InteractivityStateShape,\n  Context extends InteractivityContextShape,\n  Actions extends InteractivityActionShape,\n  Callbacks extends InteractivityCallbackShape,\n>(config: {\n  readonly namespace: Namespace;\n  readonly state: State;\n  readonly context: Context;\n  readonly actions: Actions;\n  readonly callbacks: Callbacks;\n}): TypedInteractivityStore<Namespace, State, Context, Actions, Callbacks> {\n  return {\n    namespace: config.namespace,\n    state: config.state,\n    context: config.context,\n    actions: config.actions,\n    callbacks: config.callbacks,\n    directive: {\n      interactive: config.namespace,\n      action<Key extends InteractivityMethodKey<Actions>>(key: Key) {\n        return `actions.${key}` as InteractivityDirectivePath<'actions', Key>;\n      },\n      callback<Key extends InteractivityMethodKey<Callbacks>>(key: Key) {\n        return `callbacks.${key}` as InteractivityDirectivePath<'callbacks', Key>;\n      },\n      state<Key extends InteractivityKey<State>>(key: Key) {\n        return `state.${key}` as InteractivityDirectivePath<'state', Key>;\n      },\n      context<Key extends InteractivityKey<Context>>(key: Key) {\n        return `context.${key}` as InteractivityDirectivePath<'context', Key>;\n      },\n      negate<Path extends string>(path: Path) {\n        return `!${path}` as NegatedInteractivityDirectivePath<Path>;\n      },\n    },\n    createContext(value) {\n      return value;\n    },\n  };\n}\n\ntype InteractivityActionHandler = InteractivityCallable;\n\nexport interface {{pascalCase}}StoreActions {\n  handleClick: InteractivityActionHandler;\n  handleMouseEnter: InteractivityActionHandler;\n  handleMouseLeave: InteractivityActionHandler;\n  reset: InteractivityActionHandler;\n}\n\nexport interface {{pascalCase}}StoreCallbacks {}\n\nexport const {{slugCamelCase}}Store = defineInteractivityStore({\n  namespace: '{{slugKebabCase}}',\n  state: {} as {{pascalCase}}State,\n  context: {} as {{pascalCase}}Context,\n  actions: {} as {{pascalCase}}StoreActions,\n  callbacks: {} as {{pascalCase}}StoreCallbacks,\n});\n";
 export declare const INTERACTIVITY_SCRIPT_TEMPLATE = "/**\n * WordPress Interactivity API implementation for {{title}} block\n */\nimport { store, getContext, getElement, withSyncEvent } from '@wordpress/interactivity';\nimport {\n  {{slugCamelCase}}Store,\n  type {{pascalCase}}StoreActions,\n} from './interactivity-store';\nimport type { {{pascalCase}}Context, {{pascalCase}}State } from './types';\n\nfunction getBlockContext() {\n  return getContext<{{pascalCase}}Context>();\n}\n\nconst actions: {{pascalCase}}StoreActions = {\n  // Handle block click\n  handleClick: () => {\n    const context = getBlockContext();\n    const { ref } = getElement();\n\n    if (!ref) {\n      return;\n    }\n\n    if (context.maxClicks > 0 && context.clicks >= context.maxClicks) {\n      return;\n    }\n\n    const previousClicks = context.clicks;\n\n    // Increment click counter\n    context.clicks += 1;\n\n    // Trigger animation\n    if (context.animation !== 'none') {\n      context.isAnimating = true;\n      setTimeout(() => {\n        context.isAnimating = false;\n      }, 1000);\n    }\n\n    // Emit custom event\n    ref.dispatchEvent(new CustomEvent('{{slugKebabCase}}:click', {\n      detail: { clicks: context.clicks }\n    }));\n\n    // Check if max clicks reached\n    if (context.maxClicks > 0 && previousClicks < context.maxClicks && context.clicks === context.maxClicks) {\n      ref.dispatchEvent(new CustomEvent('{{slugKebabCase}}:complete', {\n        detail: { totalClicks: context.clicks }\n      }));\n    }\n  },\n\n  // Handle hover events\n  handleMouseEnter: () => {\n    const context = getBlockContext();\n    if (context.animation === 'none') return;\n    context.isAnimating = true;\n  },\n\n  handleMouseLeave: () => {\n    const context = getBlockContext();\n    if (context.animation === 'none') return;\n    context.isAnimating = false;\n  },\n\n  // Reset counter\n  reset: withSyncEvent((event: Event) => {\n    event.stopPropagation();\n    const context = getBlockContext();\n    context.clicks = 0;\n    context.isAnimating = false;\n  })\n};\n\nconst state = {\n    get clicks() {\n      return getBlockContext().clicks;\n    },\n    get isAnimating() {\n      return getBlockContext().isAnimating;\n    },\n    get isVisible() {\n      return getBlockContext().isVisible;\n    },\n    get progress() {\n      const context = getBlockContext();\n      const clampedClicks =\n        context.maxClicks > 0\n          ? Math.min(context.clicks, context.maxClicks)\n          : context.clicks;\n      return context.maxClicks > 0 ? (clampedClicks / context.maxClicks) * 100 : 0;\n    },\n    get clampedClicks() {\n      const context = getBlockContext();\n      return context.maxClicks > 0\n        ? Math.min(context.clicks, context.maxClicks)\n        : context.clicks;\n    },\n    get isComplete() {\n      const context = getBlockContext();\n      return context.clicks >= context.maxClicks && context.maxClicks > 0;\n    }\n} satisfies {{pascalCase}}State;\n\n// Store configuration\nstore({{slugCamelCase}}Store.namespace, {\n  // State - reactive data that updates the UI\n  state,\n  actions,\n  callbacks: {{slugCamelCase}}Store.callbacks,\n});\n";
 export declare const INTERACTIVITY_VALIDATORS_TEMPLATE = "import typia from 'typia';\nimport currentManifest from \"./manifest-defaults-document\";\nimport { {{pascalCase}}Attributes, {{pascalCase}}ValidationResult } from \"./types\";\nimport { createTemplateValidatorToolkit } from \"./validator-toolkit\";\n\nconst scaffoldValidators = createTemplateValidatorToolkit<{{pascalCase}}Attributes>({\n  assert: typia.createAssert<{{pascalCase}}Attributes>(),\n  clone: typia.misc.createClone<{{pascalCase}}Attributes>() as (\n    value: {{pascalCase}}Attributes,\n  ) => {{pascalCase}}Attributes,\n  is: typia.createIs<{{pascalCase}}Attributes>(),\n  manifest: currentManifest,\n  prune: typia.misc.createPrune<{{pascalCase}}Attributes>(),\n  random: typia.createRandom<{{pascalCase}}Attributes>() as (\n    ...args: unknown[]\n  ) => {{pascalCase}}Attributes,\n  validate: typia.createValidate<{{pascalCase}}Attributes>(),\n});\n\nexport const validate{{pascalCase}}Attributes =\n  scaffoldValidators.validateAttributes as (\n    attributes: unknown,\n  ) => {{pascalCase}}ValidationResult;\n\nexport const validators = scaffoldValidators.validators;\n\nexport const sanitize{{pascalCase}}Attributes =\n  scaffoldValidators.sanitizeAttributes as (\n    attributes: Partial<{{pascalCase}}Attributes>,\n  ) => {{pascalCase}}Attributes;\n\n/**\n * Runtime type guard for checking if an object is {{pascalCase}}Attributes.\n */\nexport const is{{pascalCase}}Attributes = (obj: unknown): obj is {{pascalCase}}Attributes => {\n  return validators.is(obj);\n};\n\nexport const createAttributeUpdater = scaffoldValidators.createAttributeUpdater;\n";

package/dist/runtime/built-in-block-code-templates/interactivity.js

@@ -428,7 +428,9 @@ type InteractivityActionShape = object;
 type InteractivityCallbackShape = object;
 type InteractivityContextShape = object;
 type InteractivityStateShape = object;
-type InteractivityCallable = CallableFunction;
+type InteractivityCallable =
+  | ((...args: unknown[]) => unknown)
+  | ReturnType<typeof import('@wordpress/interactivity').withSyncEvent>;
 type InteractivityKey<T extends object> = Extract<keyof T, string>;
 type InteractivityMethodKey<T extends object> = {
   [Key in InteractivityKey<T>]: T[Key] extends InteractivityCallable ? Key : never;
@@ -531,7 +533,7 @@ export function defineInteractivityStore<
   };
 }
 
-type InteractivityActionHandler = CallableFunction;
+type InteractivityActionHandler = InteractivityCallable;
 
 export interface {{pascalCase}}StoreActions {
   handleClick: InteractivityActionHandler;

package/dist/runtime/cli-add-block-json.d.ts

@@ -0,0 +1,31 @@
+import type { WorkspaceInventory } from "./workspace-inventory.js";
+/**
+ * Resolve an existing workspace block inventory entry by slug.
+ *
+ * @param inventory Parsed workspace inventory that owns available blocks.
+ * @param blockSlug Workspace block slug to locate.
+ * @returns The matching workspace block inventory entry.
+ * @throws {Error} When the block slug is not present in the inventory.
+ */
+export declare function resolveWorkspaceBlock(inventory: WorkspaceInventory, blockSlug: string): WorkspaceInventory["blocks"][number];
+/**
+ * Read and validate a workspace block's `block.json` metadata from disk.
+ *
+ * @param projectDir Absolute workspace root directory.
+ * @param blockSlug Workspace block slug whose metadata should be read.
+ * @returns Parsed block metadata and the absolute `block.json` path.
+ * @throws {Error} When the file is missing or cannot be parsed as scaffold metadata.
+ */
+export declare function readWorkspaceBlockJson(projectDir: string, blockSlug: string): {
+    blockJson: Record<string, unknown>;
+    blockJsonPath: string;
+};
+/**
+ * Return a mutable `blockHooks` object for a parsed block metadata document.
+ *
+ * @param blockJson Parsed block metadata object that may be mutated.
+ * @param blockJsonRelativePath Relative path used in validation error messages.
+ * @returns The existing or newly created mutable `blockHooks` map.
+ * @throws {Error} When `blockHooks` exists but is not an object.
+ */
+export declare function getMutableBlockHooks(blockJson: Record<string, unknown>, blockJsonRelativePath: string): Record<string, string>;

package/dist/runtime/cli-add-block-json.js

@@ -0,0 +1,65 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parseScaffoldBlockMetadata } from "@wp-typia/block-runtime/blocks";
+/**
+ * Resolve an existing workspace block inventory entry by slug.
+ *
+ * @param inventory Parsed workspace inventory that owns available blocks.
+ * @param blockSlug Workspace block slug to locate.
+ * @returns The matching workspace block inventory entry.
+ * @throws {Error} When the block slug is not present in the inventory.
+ */
+export function resolveWorkspaceBlock(inventory, blockSlug) {
+    const block = inventory.blocks.find((entry) => entry.slug === blockSlug);
+    if (!block) {
+        throw new Error(`Unknown workspace block "${blockSlug}". Choose one of: ${inventory.blocks.map((entry) => entry.slug).join(", ")}`);
+    }
+    return block;
+}
+/**
+ * Read and validate a workspace block's `block.json` metadata from disk.
+ *
+ * @param projectDir Absolute workspace root directory.
+ * @param blockSlug Workspace block slug whose metadata should be read.
+ * @returns Parsed block metadata and the absolute `block.json` path.
+ * @throws {Error} When the file is missing or cannot be parsed as scaffold metadata.
+ */
+export function readWorkspaceBlockJson(projectDir, blockSlug) {
+    const blockJsonPath = path.join(projectDir, "src", "blocks", blockSlug, "block.json");
+    if (!fs.existsSync(blockJsonPath)) {
+        throw new Error(`Missing ${path.relative(projectDir, blockJsonPath)} for workspace block "${blockSlug}".`);
+    }
+    let blockJson;
+    try {
+        blockJson = parseScaffoldBlockMetadata(JSON.parse(fs.readFileSync(blockJsonPath, "utf8")));
+    }
+    catch (error) {
+        throw new Error(error instanceof Error
+            ? `Failed to parse ${path.relative(projectDir, blockJsonPath)}: ${error.message}`
+            : `Failed to parse ${path.relative(projectDir, blockJsonPath)}.`);
+    }
+    return {
+        blockJson,
+        blockJsonPath,
+    };
+}
+/**
+ * Return a mutable `blockHooks` object for a parsed block metadata document.
+ *
+ * @param blockJson Parsed block metadata object that may be mutated.
+ * @param blockJsonRelativePath Relative path used in validation error messages.
+ * @returns The existing or newly created mutable `blockHooks` map.
+ * @throws {Error} When `blockHooks` exists but is not an object.
+ */
+export function getMutableBlockHooks(blockJson, blockJsonRelativePath) {
+    const blockHooks = blockJson.blockHooks;
+    if (blockHooks === undefined) {
+        const nextHooks = {};
+        blockJson.blockHooks = nextHooks;
+        return nextHooks;
+    }
+    if (!blockHooks || typeof blockHooks !== "object" || Array.isArray(blockHooks)) {
+        throw new Error(`${blockJsonRelativePath} must define blockHooks as an object when present.`);
+    }
+    return blockHooks;
+}

package/dist/runtime/cli-add-collision.d.ts

@@ -0,0 +1,129 @@
+import type { WorkspaceInventory } from "./workspace-inventory.js";
+type ScaffoldFilesystemCollision = {
+    label: string;
+    relativePath: string;
+};
+type ScaffoldInventoryCollision<TEntry> = {
+    entries: readonly TEntry[];
+    exists: (entry: TEntry) => boolean;
+    message: string;
+};
+/**
+ * Ensure scaffold targets do not already exist on disk or in workspace inventory.
+ *
+ * @param options Collision checks to run before writing scaffold files.
+ * @throws {Error} When a filesystem path or inventory entry already exists.
+ */
+export declare function assertScaffoldDoesNotExist<TEntry>(options: {
+    projectDir: string;
+    filesystemCollisions: readonly ScaffoldFilesystemCollision[];
+    inventoryCollision?: ScaffoldInventoryCollision<TEntry>;
+}): void;
+/**
+ * Ensure a block variation scaffold does not already exist.
+ *
+ * @param projectDir Absolute workspace root used to resolve scaffold paths.
+ * @param blockSlug Existing workspace block slug that owns the variation.
+ * @param variationSlug Normalized variation slug that would be created.
+ * @param inventory Current workspace inventory used for duplicate detection.
+ * @throws {Error} When the variation file or inventory entry already exists.
+ */
+export declare function assertVariationDoesNotExist(projectDir: string, blockSlug: string, variationSlug: string, inventory: WorkspaceInventory): void;
+/**
+ * Ensure a block style scaffold does not already exist.
+ *
+ * @param projectDir Absolute workspace root used to resolve scaffold paths.
+ * @param blockSlug Existing workspace block slug that owns the style.
+ * @param styleSlug Normalized style slug that would be created.
+ * @param inventory Current workspace inventory used for duplicate detection.
+ * @throws {Error} When the style file or inventory entry already exists.
+ */
+export declare function assertBlockStyleDoesNotExist(projectDir: string, blockSlug: string, styleSlug: string, inventory: WorkspaceInventory): void;
+/**
+ * Ensure a block transform scaffold does not already exist.
+ *
+ * @param projectDir Absolute workspace root used to resolve scaffold paths.
+ * @param blockSlug Existing workspace block slug that owns the transform.
+ * @param transformSlug Normalized transform slug that would be created.
+ * @param inventory Current workspace inventory used for duplicate detection.
+ * @throws {Error} When the transform file or inventory entry already exists.
+ */
+export declare function assertBlockTransformDoesNotExist(projectDir: string, blockSlug: string, transformSlug: string, inventory: WorkspaceInventory): void;
+/**
+ * Ensure a pattern scaffold does not already exist on disk or in inventory.
+ *
+ * Delegates filesystem and inventory checks to `assertScaffoldDoesNotExist`.
+ *
+ * @param projectDir Absolute workspace root used to resolve scaffold paths.
+ * @param patternSlug Normalized pattern slug that would be created.
+ * @param inventory Current workspace inventory used for duplicate detection.
+ * @throws {Error} When the pattern file or inventory entry already exists.
+ */
+export declare function assertPatternDoesNotExist(projectDir: string, patternSlug: string, inventory: WorkspaceInventory): void;
+/**
+ * Ensure a binding source scaffold does not already exist on disk or in inventory.
+ *
+ * Delegates filesystem and inventory checks to `assertScaffoldDoesNotExist`.
+ *
+ * @param projectDir Absolute workspace root used to resolve scaffold paths.
+ * @param bindingSourceSlug Normalized binding source slug that would be created.
+ * @param inventory Current workspace inventory used for duplicate detection.
+ * @throws {Error} When the binding directory or inventory entry already exists.
+ */
+export declare function assertBindingSourceDoesNotExist(projectDir: string, bindingSourceSlug: string, inventory: WorkspaceInventory): void;
+/**
+ * Ensure a REST resource scaffold does not already exist on disk or in inventory.
+ *
+ * Delegates filesystem and inventory checks to `assertScaffoldDoesNotExist`.
+ *
+ * @param projectDir Absolute workspace root used to resolve scaffold paths.
+ * @param restResourceSlug Normalized REST resource slug that would be created.
+ * @param inventory Current workspace inventory used for duplicate detection.
+ * @throws {Error} When REST resource files or inventory entry already exist.
+ */
+export declare function assertRestResourceDoesNotExist(projectDir: string, restResourceSlug: string, inventory: WorkspaceInventory): void;
+/**
+ * Ensure a DataViews admin screen scaffold does not already exist on disk or in
+ * the workspace inventory.
+ *
+ * @param projectDir Workspace root directory.
+ * @param adminViewSlug Normalized admin screen slug.
+ * @param inventory Parsed workspace inventory.
+ * @throws {Error} When the directory, PHP bootstrap, or inventory entry already exists.
+ */
+export declare function assertAdminViewDoesNotExist(projectDir: string, adminViewSlug: string, inventory: WorkspaceInventory): void;
+/**
+ * Ensure a workflow ability scaffold does not already exist on disk or in the
+ * workspace inventory.
+ *
+ * The check covers the generated `src/abilities/<slug>` directory,
+ * `inc/abilities/<slug>.php`, and any matching `inventory.abilities` entry.
+ *
+ * @param projectDir Workspace root directory.
+ * @param abilitySlug Normalized workflow ability slug.
+ * @param inventory Parsed workspace inventory.
+ * @throws {Error} When the ability directory, PHP bootstrap, or inventory entry already exists.
+ */
+export declare function assertAbilityDoesNotExist(projectDir: string, abilitySlug: string, inventory: WorkspaceInventory): void;
+/**
+ * Ensure an AI feature scaffold does not already exist on disk or in inventory.
+ *
+ * Delegates filesystem and inventory checks to `assertScaffoldDoesNotExist`.
+ *
+ * @param projectDir Absolute workspace root used to resolve scaffold paths.
+ * @param aiFeatureSlug Normalized AI feature slug that would be created.
+ * @param inventory Current workspace inventory used for duplicate detection.
+ * @throws {Error} When AI feature files or inventory entry already exist.
+ */
+export declare function assertAiFeatureDoesNotExist(projectDir: string, aiFeatureSlug: string, inventory: WorkspaceInventory): void;
+/**
+ * Ensure an editor plugin scaffold does not already exist on disk or in the
+ * workspace inventory.
+ *
+ * @param projectDir Workspace root directory.
+ * @param editorPluginSlug Normalized editor plugin slug.
+ * @param inventory Parsed workspace inventory.
+ * @throws {Error} When the directory or inventory entry already exists.
+ */
+export declare function assertEditorPluginDoesNotExist(projectDir: string, editorPluginSlug: string, inventory: WorkspaceInventory): void;
+export {};

package/dist/runtime/cli-add-collision.js

@@ -0,0 +1,293 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Ensure scaffold targets do not already exist on disk or in workspace inventory.
+ *
+ * @param options Collision checks to run before writing scaffold files.
+ * @throws {Error} When a filesystem path or inventory entry already exists.
+ */
+export function assertScaffoldDoesNotExist(options) {
+    for (const collision of options.filesystemCollisions) {
+        const targetPath = path.join(options.projectDir, collision.relativePath);
+        if (fs.existsSync(targetPath)) {
+            throw new Error(`${collision.label} already exists at ${path.relative(options.projectDir, targetPath)}. Choose a different name.`);
+        }
+    }
+    if (options.inventoryCollision &&
+        options.inventoryCollision.entries.some(options.inventoryCollision.exists)) {
+        throw new Error(options.inventoryCollision.message);
+    }
+}
+/**
+ * Ensure a block variation scaffold does not already exist.
+ *
+ * @param projectDir Absolute workspace root used to resolve scaffold paths.
+ * @param blockSlug Existing workspace block slug that owns the variation.
+ * @param variationSlug Normalized variation slug that would be created.
+ * @param inventory Current workspace inventory used for duplicate detection.
+ * @throws {Error} When the variation file or inventory entry already exists.
+ */
+export function assertVariationDoesNotExist(projectDir, blockSlug, variationSlug, inventory) {
+    assertScaffoldDoesNotExist({
+        filesystemCollisions: [
+            {
+                label: "A variation",
+                relativePath: path.join("src", "blocks", blockSlug, "variations", `${variationSlug}.ts`),
+            },
+        ],
+        inventoryCollision: {
+            entries: inventory.variations,
+            exists: (entry) => entry.block === blockSlug && entry.slug === variationSlug,
+            message: `A variation inventory entry already exists for ${blockSlug}/${variationSlug}. Choose a different name.`,
+        },
+        projectDir,
+    });
+}
+/**
+ * Ensure a block style scaffold does not already exist.
+ *
+ * @param projectDir Absolute workspace root used to resolve scaffold paths.
+ * @param blockSlug Existing workspace block slug that owns the style.
+ * @param styleSlug Normalized style slug that would be created.
+ * @param inventory Current workspace inventory used for duplicate detection.
+ * @throws {Error} When the style file or inventory entry already exists.
+ */
+export function assertBlockStyleDoesNotExist(projectDir, blockSlug, styleSlug, inventory) {
+    assertScaffoldDoesNotExist({
+        filesystemCollisions: [
+            {
+                label: "A block style",
+                relativePath: path.join("src", "blocks", blockSlug, "styles", `${styleSlug}.ts`),
+            },
+        ],
+        inventoryCollision: {
+            entries: inventory.blockStyles,
+            exists: (entry) => entry.block === blockSlug && entry.slug === styleSlug,
+            message: `A block style inventory entry already exists for ${blockSlug}/${styleSlug}. Choose a different name.`,
+        },
+        projectDir,
+    });
+}
+/**
+ * Ensure a block transform scaffold does not already exist.
+ *
+ * @param projectDir Absolute workspace root used to resolve scaffold paths.
+ * @param blockSlug Existing workspace block slug that owns the transform.
+ * @param transformSlug Normalized transform slug that would be created.
+ * @param inventory Current workspace inventory used for duplicate detection.
+ * @throws {Error} When the transform file or inventory entry already exists.
+ */
+export function assertBlockTransformDoesNotExist(projectDir, blockSlug, transformSlug, inventory) {
+    assertScaffoldDoesNotExist({
+        filesystemCollisions: [
+            {
+                label: "A block transform",
+                relativePath: path.join("src", "blocks", blockSlug, "transforms", `${transformSlug}.ts`),
+            },
+        ],
+        inventoryCollision: {
+            entries: inventory.blockTransforms,
+            exists: (entry) => entry.block === blockSlug && entry.slug === transformSlug,
+            message: `A block transform inventory entry already exists for ${blockSlug}/${transformSlug}. Choose a different name.`,
+        },
+        projectDir,
+    });
+}
+/**
+ * Ensure a pattern scaffold does not already exist on disk or in inventory.
+ *
+ * Delegates filesystem and inventory checks to `assertScaffoldDoesNotExist`.
+ *
+ * @param projectDir Absolute workspace root used to resolve scaffold paths.
+ * @param patternSlug Normalized pattern slug that would be created.
+ * @param inventory Current workspace inventory used for duplicate detection.
+ * @throws {Error} When the pattern file or inventory entry already exists.
+ */
+export function assertPatternDoesNotExist(projectDir, patternSlug, inventory) {
+    assertScaffoldDoesNotExist({
+        filesystemCollisions: [
+            {
+                label: "A pattern",
+                relativePath: path.join("src", "patterns", `${patternSlug}.php`),
+            },
+        ],
+        inventoryCollision: {
+            entries: inventory.patterns,
+            exists: (entry) => entry.slug === patternSlug,
+            message: `A pattern inventory entry already exists for ${patternSlug}. Choose a different name.`,
+        },
+        projectDir,
+    });
+}
+/**
+ * Ensure a binding source scaffold does not already exist on disk or in inventory.
+ *
+ * Delegates filesystem and inventory checks to `assertScaffoldDoesNotExist`.
+ *
+ * @param projectDir Absolute workspace root used to resolve scaffold paths.
+ * @param bindingSourceSlug Normalized binding source slug that would be created.
+ * @param inventory Current workspace inventory used for duplicate detection.
+ * @throws {Error} When the binding directory or inventory entry already exists.
+ */
+export function assertBindingSourceDoesNotExist(projectDir, bindingSourceSlug, inventory) {
+    assertScaffoldDoesNotExist({
+        filesystemCollisions: [
+            {
+                label: "A binding source",
+                relativePath: path.join("src", "bindings", bindingSourceSlug),
+            },
+        ],
+        inventoryCollision: {
+            entries: inventory.bindingSources,
+            exists: (entry) => entry.slug === bindingSourceSlug,
+            message: `A binding source inventory entry already exists for ${bindingSourceSlug}. Choose a different name.`,
+        },
+        projectDir,
+    });
+}
+/**
+ * Ensure a REST resource scaffold does not already exist on disk or in inventory.
+ *
+ * Delegates filesystem and inventory checks to `assertScaffoldDoesNotExist`.
+ *
+ * @param projectDir Absolute workspace root used to resolve scaffold paths.
+ * @param restResourceSlug Normalized REST resource slug that would be created.
+ * @param inventory Current workspace inventory used for duplicate detection.
+ * @throws {Error} When REST resource files or inventory entry already exist.
+ */
+export function assertRestResourceDoesNotExist(projectDir, restResourceSlug, inventory) {
+    assertScaffoldDoesNotExist({
+        filesystemCollisions: [
+            {
+                label: "A REST resource",
+                relativePath: path.join("src", "rest", restResourceSlug),
+            },
+            {
+                label: "A REST resource bootstrap",
+                relativePath: path.join("inc", "rest", `${restResourceSlug}.php`),
+            },
+        ],
+        inventoryCollision: {
+            entries: inventory.restResources,
+            exists: (entry) => entry.slug === restResourceSlug,
+            message: `A REST resource inventory entry already exists for ${restResourceSlug}. Choose a different name.`,
+        },
+        projectDir,
+    });
+}
+/**
+ * Ensure a DataViews admin screen scaffold does not already exist on disk or in
+ * the workspace inventory.
+ *
+ * @param projectDir Workspace root directory.
+ * @param adminViewSlug Normalized admin screen slug.
+ * @param inventory Parsed workspace inventory.
+ * @throws {Error} When the directory, PHP bootstrap, or inventory entry already exists.
+ */
+export function assertAdminViewDoesNotExist(projectDir, adminViewSlug, inventory) {
+    assertScaffoldDoesNotExist({
+        filesystemCollisions: [
+            {
+                label: "An admin view",
+                relativePath: path.join("src", "admin-views", adminViewSlug),
+            },
+            {
+                label: "An admin view bootstrap",
+                relativePath: path.join("inc", "admin-views", `${adminViewSlug}.php`),
+            },
+        ],
+        inventoryCollision: {
+            entries: inventory.adminViews,
+            exists: (entry) => entry.slug === adminViewSlug,
+            message: `An admin view inventory entry already exists for ${adminViewSlug}. Choose a different name.`,
+        },
+        projectDir,
+    });
+}
+/**
+ * Ensure a workflow ability scaffold does not already exist on disk or in the
+ * workspace inventory.
+ *
+ * The check covers the generated `src/abilities/<slug>` directory,
+ * `inc/abilities/<slug>.php`, and any matching `inventory.abilities` entry.
+ *
+ * @param projectDir Workspace root directory.
+ * @param abilitySlug Normalized workflow ability slug.
+ * @param inventory Parsed workspace inventory.
+ * @throws {Error} When the ability directory, PHP bootstrap, or inventory entry already exists.
+ */
+export function assertAbilityDoesNotExist(projectDir, abilitySlug, inventory) {
+    assertScaffoldDoesNotExist({
+        filesystemCollisions: [
+            {
+                label: "An ability scaffold",
+                relativePath: path.join("src", "abilities", abilitySlug),
+            },
+            {
+                label: "An ability bootstrap",
+                relativePath: path.join("inc", "abilities", `${abilitySlug}.php`),
+            },
+        ],
+        inventoryCollision: {
+            entries: inventory.abilities,
+            exists: (entry) => entry.slug === abilitySlug,
+            message: `An ability inventory entry already exists for ${abilitySlug}. Choose a different name.`,
+        },
+        projectDir,
+    });
+}
+/**
+ * Ensure an AI feature scaffold does not already exist on disk or in inventory.
+ *
+ * Delegates filesystem and inventory checks to `assertScaffoldDoesNotExist`.
+ *
+ * @param projectDir Absolute workspace root used to resolve scaffold paths.
+ * @param aiFeatureSlug Normalized AI feature slug that would be created.
+ * @param inventory Current workspace inventory used for duplicate detection.
+ * @throws {Error} When AI feature files or inventory entry already exist.
+ */
+export function assertAiFeatureDoesNotExist(projectDir, aiFeatureSlug, inventory) {
+    assertScaffoldDoesNotExist({
+        filesystemCollisions: [
+            {
+                label: "An AI feature",
+                relativePath: path.join("src", "ai-features", aiFeatureSlug),
+            },
+            {
+                label: "An AI feature bootstrap",
+                relativePath: path.join("inc", "ai-features", `${aiFeatureSlug}.php`),
+            },
+        ],
+        inventoryCollision: {
+            entries: inventory.aiFeatures,
+            exists: (entry) => entry.slug === aiFeatureSlug,
+            message: `An AI feature inventory entry already exists for ${aiFeatureSlug}. Choose a different name.`,
+        },
+        projectDir,
+    });
+}
+/**
+ * Ensure an editor plugin scaffold does not already exist on disk or in the
+ * workspace inventory.
+ *
+ * @param projectDir Workspace root directory.
+ * @param editorPluginSlug Normalized editor plugin slug.
+ * @param inventory Parsed workspace inventory.
+ * @throws {Error} When the directory or inventory entry already exists.
+ */
+export function assertEditorPluginDoesNotExist(projectDir, editorPluginSlug, inventory) {
+    assertScaffoldDoesNotExist({
+        filesystemCollisions: [
+            {
+                label: "An editor plugin",
+                relativePath: path.join("src", "editor-plugins", editorPluginSlug),
+            },
+        ],
+        inventoryCollision: {
+            entries: inventory.editorPlugins,
+            exists: (entry) => entry.slug === editorPluginSlug,
+            message: `An editor plugin inventory entry already exists for ${editorPluginSlug}. Choose a different name.`,
+        },
+        projectDir,
+    });
+}

package/dist/runtime/cli-add-filesystem.d.ts

@@ -0,0 +1,29 @@
+import type { WorkspaceMutationSnapshot } from "./cli-add-types.js";
+import type { WorkspaceProject } from "./workspace-project.js";
+/**
+ * Resolve the primary PHP bootstrap file for an official workspace.
+ *
+ * @param workspace Workspace metadata that provides `packageName` and `projectDir`.
+ * @returns Absolute path to `<packageBase>.php` in the workspace root.
+ */
+export declare function getWorkspaceBootstrapPath(workspace: WorkspaceProject): string;
+/**
+ * Apply a text transform to an existing file only when the contents change.
+ */
+export declare function patchFile(filePath: string, transform: (source: string) => string): Promise<void>;
+/**
+ * Read a file when it exists and otherwise return `null`.
+ */
+export declare function readOptionalFile(filePath: string): Promise<string | null>;
+/**
+ * Restore a file to its captured source, deleting it when the snapshot was `null`.
+ */
+export declare function restoreOptionalFile(filePath: string, source: string | null): Promise<void>;
+/**
+ * Capture the current contents of a set of workspace files for rollback.
+ */
+export declare function snapshotWorkspaceFiles(filePaths: string[]): Promise<WorkspaceMutationSnapshot["fileSources"]>;
+/**
+ * Undo a partially applied workspace mutation from a captured snapshot.
+ */
+export declare function rollbackWorkspaceMutation(snapshot: WorkspaceMutationSnapshot): Promise<void>;