@wp-typia/project-tools 0.16.13 → 0.17.0

package/dist/runtime/scaffold-template-variables.js

@@ -0,0 +1,117 @@
+import { buildTemplateVariablesFromBlockSpec, createBuiltInBlockSpec, } from './block-generator-service.js';
+import { getPackageVersions } from './package-versions.js';
+import { buildBlockCssClassName, buildFrontendCssClassName, resolveScaffoldIdentifiers, } from './scaffold-identifiers.js';
+import { BUILTIN_BLOCK_METADATA_VERSION, COMPOUND_CHILD_BLOCK_METADATA_DEFAULTS, getBuiltInTemplateMetadataDefaults, } from './template-defaults.js';
+import { getTemplateById, isBuiltInTemplateId, } from './template-registry.js';
+import { toPascalCase, toSnakeCase, } from './string-case.js';
+/**
+ * Build the normalized template variables used by scaffold rendering.
+ *
+ * @param templateId Selected scaffold template identifier.
+ * @param answers Normalized scaffold answers collected from defaults, flags, and prompts.
+ * @returns Template variables ready for file interpolation and generated artifacts.
+ */
+export function getTemplateVariables(templateId, answers) {
+    if (isBuiltInTemplateId(templateId)) {
+        return buildTemplateVariablesFromBlockSpec(createBuiltInBlockSpec({
+            answers,
+            dataStorageMode: answers.dataStorageMode,
+            persistencePolicy: answers.persistencePolicy,
+            templateId,
+        }));
+    }
+    const { apiClientPackageVersion, blockRuntimePackageVersion, blockTypesPackageVersion, projectToolsPackageVersion, restPackageVersion, } = getPackageVersions();
+    const template = isBuiltInTemplateId(templateId) ? getTemplateById(templateId) : null;
+    const metadataDefaults = isBuiltInTemplateId(templateId)
+        ? getBuiltInTemplateMetadataDefaults(templateId)
+        : null;
+    const identifiers = resolveScaffoldIdentifiers({
+        namespace: answers.namespace,
+        phpPrefix: answers.phpPrefix,
+        slug: answers.slug,
+        textDomain: answers.textDomain,
+    });
+    const slug = identifiers.slug;
+    const slugSnakeCase = toSnakeCase(slug);
+    const pascalCase = toPascalCase(slug);
+    const title = answers.title.trim();
+    const namespace = identifiers.namespace;
+    const description = answers.description.trim();
+    const textDomain = identifiers.textDomain;
+    const phpPrefix = identifiers.phpPrefix;
+    const phpPrefixUpper = phpPrefix.toUpperCase();
+    const compoundChildTitle = `${title} Item`;
+    const cssClassName = buildBlockCssClassName(namespace, slug);
+    const compoundChildCssClassName = buildBlockCssClassName(namespace, `${slug}-item`);
+    const compoundPersistenceEnabled = templateId === 'persistence'
+        ? true
+        : templateId === 'compound'
+            ? Boolean(answers.dataStorageMode || answers.persistencePolicy)
+            : false;
+    const dataStorageMode = templateId === 'persistence' || compoundPersistenceEnabled
+        ? answers.dataStorageMode ?? 'custom-table'
+        : 'custom-table';
+    const persistencePolicy = templateId === 'persistence' || compoundPersistenceEnabled
+        ? answers.persistencePolicy ?? 'authenticated'
+        : 'authenticated';
+    return {
+        apiClientPackageVersion,
+        author: answers.author.trim(),
+        blockRuntimePackageVersion,
+        blockMetadataVersion: BUILTIN_BLOCK_METADATA_VERSION,
+        blockTypesPackageVersion,
+        category: metadataDefaults?.category ?? template?.defaultCategory ?? 'widgets',
+        icon: metadataDefaults?.icon ?? 'smiley',
+        compoundChildTitle,
+        compoundChildCategory: COMPOUND_CHILD_BLOCK_METADATA_DEFAULTS.category,
+        compoundChildCssClassName,
+        compoundChildIcon: COMPOUND_CHILD_BLOCK_METADATA_DEFAULTS.icon,
+        compoundChildTitleJson: JSON.stringify(compoundChildTitle),
+        compoundPersistenceEnabled: compoundPersistenceEnabled ? 'true' : 'false',
+        projectToolsPackageVersion,
+        cssClassName,
+        dataStorageMode,
+        dashCase: slug,
+        description,
+        descriptionJson: JSON.stringify(description),
+        frontendCssClassName: buildFrontendCssClassName(cssClassName),
+        queryAllowedControlsJson: JSON.stringify([], null, 2),
+        queryPostType: answers.queryPostType?.trim() || 'post',
+        queryPostTypeJson: JSON.stringify(answers.queryPostType?.trim() || 'post'),
+        queryVariationNamespace: `${namespace}/${slug}`,
+        queryVariationNamespaceJson: JSON.stringify(`${namespace}/${slug}`),
+        isAuthenticatedPersistencePolicy: persistencePolicy === 'authenticated' ? 'true' : 'false',
+        isPublicPersistencePolicy: persistencePolicy === 'public' ? 'true' : 'false',
+        bootstrapCredentialDeclarations: persistencePolicy === 'public'
+            ? "publicWriteExpiresAt?: number & tags.Type< 'uint32' >;\n\tpublicWriteToken?: string & tags.MinLength< 1 > & tags.MaxLength< 512 >;"
+            : "restNonce?: string & tags.MinLength< 1 > & tags.MaxLength< 128 >;",
+        persistencePolicyDescriptionJson: JSON.stringify(persistencePolicy === 'authenticated'
+            ? 'Writes require a logged-in user and a valid REST nonce.'
+            : 'Anonymous writes use signed short-lived public tokens, per-request ids, and coarse rate limiting.'),
+        keyword: slug.replace(/-/g, ' '),
+        namespace,
+        needsMigration: '{{needsMigration}}',
+        pascalCase,
+        phpPrefix,
+        phpPrefixUpper,
+        restPackageVersion,
+        publicWriteRequestIdDeclaration: persistencePolicy === 'public'
+            ? "publicWriteRequestId: string & tags.MinLength< 1 > & tags.MaxLength< 128 >;"
+            : "publicWriteRequestId?: string & tags.MinLength< 1 > & tags.MaxLength< 128 >;",
+        restWriteAuthIntent: persistencePolicy === 'public'
+            ? 'public-write-protected'
+            : 'authenticated',
+        restWriteAuthMechanism: persistencePolicy === 'public' ? 'public-signed-token' : 'rest-nonce',
+        restWriteAuthMode: persistencePolicy === 'public' ? 'public-signed-token' : 'authenticated-rest-nonce',
+        slug,
+        slugCamelCase: pascalCase.charAt(0).toLowerCase() + pascalCase.slice(1),
+        slugKebabCase: slug,
+        slugSnakeCase,
+        textDomain,
+        textdomain: textDomain,
+        title,
+        titleJson: JSON.stringify(title),
+        titleCase: pascalCase,
+        persistencePolicy,
+    };
+}

package/dist/runtime/scaffold.d.ts

@@ -15,6 +15,7 @@ export interface ScaffoldAnswers {
     persistencePolicy?: PersistencePolicy;
     /** Snake_case PHP symbol prefix used for generated functions, constants, and keys. */
     phpPrefix?: string;
+    queryPostType?: string;
     slug: string;
     /** Kebab-case WordPress text domain used in block metadata and i18n strings. */
     textDomain?: string;
@@ -46,6 +47,7 @@ export interface ScaffoldTemplateVariables extends Record<string, string> {
     dashCase: string;
     dataStorageMode: DataStorageMode;
     description: string;
+    descriptionJson: string;
     frontendCssClassName: string;
     keyword: string;
     namespace: string;
@@ -53,6 +55,11 @@ export interface ScaffoldTemplateVariables extends Record<string, string> {
     pascalCase: string;
     phpPrefix: string;
     phpPrefixUpper: string;
+    queryAllowedControlsJson: string;
+    queryPostTypeJson: string;
+    queryPostType: string;
+    queryVariationNamespace: string;
+    queryVariationNamespaceJson: string;
     isAuthenticatedPersistencePolicy: "false" | "true";
     isPublicPersistencePolicy: "false" | "true";
     bootstrapCredentialDeclarations: string;
@@ -81,25 +88,32 @@ export interface ScaffoldTemplateVariables extends Record<string, string> {
  * can surface custom ids. Downstream code uses `isBuiltInTemplateId()` to
  * distinguish built-in templates from custom sources.
  */
-interface ResolveTemplateOptions {
+export interface ResolveTemplateOptions {
     isInteractive?: boolean;
     selectTemplate?: () => Promise<string>;
     templateId?: string;
     yes?: boolean;
 }
-interface ResolvePackageManagerOptions {
+/**
+ * Options for resolving the package manager in CLI and interactive scaffold flows.
+ */
+export interface ResolvePackageManagerOptions {
     isInteractive?: boolean;
     packageManager?: string;
     selectPackageManager?: () => Promise<PackageManagerId>;
     yes?: boolean;
 }
-interface CollectScaffoldAnswersOptions {
+/**
+ * Options for collecting scaffold answers from defaults, overrides, and prompts.
+ */
+export interface CollectScaffoldAnswersOptions {
     dataStorageMode?: DataStorageMode;
     namespace?: string;
     phpPrefix?: string;
     projectName: string;
     promptText?: (message: string, defaultValue: string, validate?: (value: string) => true | string) => Promise<string>;
     persistencePolicy?: PersistencePolicy;
+    queryPostType?: string;
     textDomain?: string;
     templateId: string;
     withTestPreset?: boolean;
@@ -139,12 +153,8 @@ export interface ScaffoldProjectResult {
     warnings: string[];
 }
 export { buildBlockCssClassName } from "./scaffold-identifiers.js";
+export { collectScaffoldAnswers, detectAuthor, getDefaultAnswers, resolvePackageManagerId, resolveTemplateId, } from "./scaffold-answer-resolution.js";
+export { getTemplateVariables } from "./scaffold-template-variables.js";
 export declare function isDataStorageMode(value: string): value is DataStorageMode;
 export declare function isPersistencePolicy(value: string): value is PersistencePolicy;
-export declare function detectAuthor(): string;
-export declare function getDefaultAnswers(projectName: string, templateId: string): ScaffoldAnswers;
-export declare function resolveTemplateId({ templateId, yes, isInteractive, selectTemplate, }: ResolveTemplateOptions): Promise<string>;
-export declare function resolvePackageManagerId({ packageManager, yes, isInteractive, selectPackageManager, }: ResolvePackageManagerOptions): Promise<PackageManagerId>;
-export declare function collectScaffoldAnswers({ projectName, templateId, yes, dataStorageMode, namespace, persistencePolicy, phpPrefix, promptText, textDomain, }: CollectScaffoldAnswersOptions): Promise<ScaffoldAnswers>;
-export declare function getTemplateVariables(templateId: string, answers: ScaffoldAnswers): ScaffoldTemplateVariables;
 export declare function scaffoldProject({ projectDir, templateId, answers, dataStorageMode, persistencePolicy, packageManager, externalLayerId, externalLayerSource, externalLayerSourceLabel, repositoryReference, cwd, allowExistingDir, noInstall, installDependencies, variant, withMigrationUi, withTestPreset, withWpEnv, }: ScaffoldProjectOptions): Promise<ScaffoldProjectResult>;

package/dist/runtime/scaffold.js

@@ -1,230 +1,34 @@
 import fs from "node:fs";
 import { promises as fsp } from "node:fs";
 import path from "node:path";
-import { execSync } from "node:child_process";
-import { PACKAGE_MANAGER_IDS, getPackageManager, } from "./package-managers.js";
+import { getPackageManager } from "./package-managers.js";
 import { buildGitignore, buildReadme, mergeTextLines, replaceTextRecursively, } from "./scaffold-apply-utils.js";
-import { buildBlockCssClassName, buildFrontendCssClassName, normalizeBlockSlug, resolveScaffoldIdentifiers, validateBlockSlug, validateNamespace, } from "./scaffold-identifiers.js";
 import { applyGeneratedProjectDxPackageJson, applyLocalDevPresetFiles, } from "./local-dev-presets.js";
 import { applyMigrationUiCapability } from "./migration-ui-capability.js";
-import { getPackageVersions } from "./package-versions.js";
 import { applyWorkspaceMigrationCapability, ensureScaffoldDirectory, isOfficialWorkspaceProject, seedBuiltInPersistenceArtifacts, writeStarterManifestFiles, } from "./scaffold-bootstrap.js";
 import { defaultInstallDependencies, normalizePackageJson, normalizePackageManagerFiles, removeUnexpectedLockfiles, } from "./scaffold-package-manager-files.js";
-import { toPascalCase, toSnakeCase, toTitleCase, } from "./string-case.js";
-import { BUILTIN_BLOCK_METADATA_VERSION, COMPOUND_CHILD_BLOCK_METADATA_DEFAULTS, getBuiltInTemplateMetadataDefaults, getRemovedBuiltInTemplateMessage, isRemovedBuiltInTemplateId, } from "./template-defaults.js";
 import { copyInterpolatedDirectory } from "./template-render.js";
-import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, TEMPLATE_IDS, getTemplateById, isBuiltInTemplateId, } from "./template-registry.js";
+import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, isBuiltInTemplateId, } from "./template-registry.js";
 import { resolveTemplateSource } from "./template-source.js";
-import { BlockGeneratorService, buildTemplateVariablesFromBlockSpec, createBuiltInBlockSpec, } from "./block-generator-service.js";
+import { BlockGeneratorService, } from "./block-generator-service.js";
+import { getTemplateVariables } from "./scaffold-template-variables.js";
 const WORKSPACE_TEMPLATE_ALIAS = "workspace";
 export const DATA_STORAGE_MODES = ["post-meta", "custom-table"];
 export const PERSISTENCE_POLICIES = ["authenticated", "public"];
 export { buildBlockCssClassName } from "./scaffold-identifiers.js";
+export { collectScaffoldAnswers, detectAuthor, getDefaultAnswers, resolvePackageManagerId, resolveTemplateId, } from "./scaffold-answer-resolution.js";
+export { getTemplateVariables } from "./scaffold-template-variables.js";
 export function isDataStorageMode(value) {
     return DATA_STORAGE_MODES.includes(value);
 }
 export function isPersistencePolicy(value) {
     return PERSISTENCE_POLICIES.includes(value);
 }
-export function detectAuthor() {
-    try {
-        return (execSync("git config user.name", {
-            encoding: "utf8",
-            stdio: ["ignore", "pipe", "ignore"],
-        }).trim() || "Your Name");
-    }
-    catch {
-        return "Your Name";
-    }
-}
-export function getDefaultAnswers(projectName, templateId) {
-    const template = isBuiltInTemplateId(templateId) ? getTemplateById(templateId) : null;
-    const slugDefault = normalizeBlockSlug(projectName) || "my-wp-typia-block";
-    return {
-        author: detectAuthor(),
-        dataStorageMode: templateId === "persistence" ? "custom-table" : undefined,
-        description: template?.description ?? "A WordPress block scaffolded from a remote template",
-        namespace: slugDefault,
-        persistencePolicy: templateId === "persistence" ? "authenticated" : undefined,
-        phpPrefix: toSnakeCase(slugDefault),
-        slug: slugDefault,
-        textDomain: slugDefault,
-        title: toTitleCase(slugDefault),
-    };
-}
 function normalizeTemplateSelection(templateId) {
     return templateId === WORKSPACE_TEMPLATE_ALIAS
         ? OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE
         : templateId;
 }
-export async function resolveTemplateId({ templateId, yes = false, isInteractive = false, selectTemplate, }) {
-    if (templateId) {
-        const normalizedTemplateId = normalizeTemplateSelection(templateId);
-        if (isRemovedBuiltInTemplateId(templateId)) {
-            throw new Error(getRemovedBuiltInTemplateMessage(templateId));
-        }
-        if (isBuiltInTemplateId(normalizedTemplateId)) {
-            return getTemplateById(normalizedTemplateId).id;
-        }
-        return normalizedTemplateId;
-    }
-    if (yes) {
-        return "basic";
-    }
-    if (!isInteractive || !selectTemplate) {
-        throw new Error(`Template is required in non-interactive mode. Use --template <${TEMPLATE_IDS.join("|")}|./path|github:owner/repo/path[#ref]|npm-package>.`);
-    }
-    return normalizeTemplateSelection(await selectTemplate());
-}
-export async function resolvePackageManagerId({ packageManager, yes = false, isInteractive = false, selectPackageManager, }) {
-    if (packageManager) {
-        return getPackageManager(packageManager).id;
-    }
-    if (yes) {
-        return "npm";
-    }
-    if (!isInteractive || !selectPackageManager) {
-        throw new Error(`Package manager is required in non-interactive mode. Use --package-manager <${PACKAGE_MANAGER_IDS.join("|")}>.`);
-    }
-    return selectPackageManager();
-}
-export async function collectScaffoldAnswers({ projectName, templateId, yes = false, dataStorageMode, namespace, persistencePolicy, phpPrefix, promptText, textDomain, }) {
-    const defaults = getDefaultAnswers(projectName, templateId);
-    if (yes) {
-        const identifiers = resolveScaffoldIdentifiers({
-            namespace: namespace ?? defaults.namespace,
-            phpPrefix,
-            slug: defaults.slug,
-            textDomain,
-        });
-        return {
-            ...defaults,
-            dataStorageMode: dataStorageMode ?? defaults.dataStorageMode,
-            namespace: identifiers.namespace,
-            persistencePolicy: persistencePolicy ?? defaults.persistencePolicy,
-            phpPrefix: identifiers.phpPrefix,
-            textDomain: identifiers.textDomain,
-        };
-    }
-    if (!promptText) {
-        throw new Error("Interactive answers require a promptText callback.");
-    }
-    const identifiers = resolveScaffoldIdentifiers({
-        namespace: namespace ?? (await promptText("Namespace", defaults.namespace, validateNamespace)),
-        phpPrefix,
-        slug: await promptText("Block slug", defaults.slug, validateBlockSlug),
-        textDomain,
-    });
-    return {
-        author: await promptText("Author", defaults.author),
-        dataStorageMode: dataStorageMode ?? defaults.dataStorageMode,
-        description: await promptText("Description", defaults.description),
-        namespace: identifiers.namespace,
-        persistencePolicy: persistencePolicy ?? defaults.persistencePolicy,
-        phpPrefix: identifiers.phpPrefix,
-        slug: identifiers.slug,
-        textDomain: identifiers.textDomain,
-        title: await promptText("Block title", toTitleCase(identifiers.slug)),
-    };
-}
-export function getTemplateVariables(templateId, answers) {
-    if (isBuiltInTemplateId(templateId)) {
-        return buildTemplateVariablesFromBlockSpec(createBuiltInBlockSpec({
-            answers,
-            dataStorageMode: answers.dataStorageMode,
-            persistencePolicy: answers.persistencePolicy,
-            templateId,
-        }));
-    }
-    const { apiClientPackageVersion, blockRuntimePackageVersion, blockTypesPackageVersion, projectToolsPackageVersion, restPackageVersion, } = getPackageVersions();
-    const template = isBuiltInTemplateId(templateId) ? getTemplateById(templateId) : null;
-    const metadataDefaults = isBuiltInTemplateId(templateId)
-        ? getBuiltInTemplateMetadataDefaults(templateId)
-        : null;
-    const identifiers = resolveScaffoldIdentifiers({
-        namespace: answers.namespace,
-        phpPrefix: answers.phpPrefix,
-        slug: answers.slug,
-        textDomain: answers.textDomain,
-    });
-    const slug = identifiers.slug;
-    const slugSnakeCase = toSnakeCase(slug);
-    const pascalCase = toPascalCase(slug);
-    const title = answers.title.trim();
-    const namespace = identifiers.namespace;
-    const description = answers.description.trim();
-    const textDomain = identifiers.textDomain;
-    const phpPrefix = identifiers.phpPrefix;
-    const phpPrefixUpper = phpPrefix.toUpperCase();
-    const compoundChildTitle = `${title} Item`;
-    const cssClassName = buildBlockCssClassName(namespace, slug);
-    const compoundChildCssClassName = buildBlockCssClassName(namespace, `${slug}-item`);
-    const compoundPersistenceEnabled = templateId === "persistence"
-        ? true
-        : templateId === "compound"
-            ? Boolean(answers.dataStorageMode || answers.persistencePolicy)
-            : false;
-    const dataStorageMode = templateId === "persistence" || compoundPersistenceEnabled
-        ? answers.dataStorageMode ?? "custom-table"
-        : "custom-table";
-    const persistencePolicy = templateId === "persistence" || compoundPersistenceEnabled
-        ? answers.persistencePolicy ?? "authenticated"
-        : "authenticated";
-    return {
-        apiClientPackageVersion,
-        author: answers.author.trim(),
-        blockRuntimePackageVersion,
-        blockMetadataVersion: BUILTIN_BLOCK_METADATA_VERSION,
-        blockTypesPackageVersion,
-        category: metadataDefaults?.category ?? template?.defaultCategory ?? "widgets",
-        icon: metadataDefaults?.icon ?? "smiley",
-        compoundChildTitle,
-        compoundChildCategory: COMPOUND_CHILD_BLOCK_METADATA_DEFAULTS.category,
-        compoundChildCssClassName,
-        compoundChildIcon: COMPOUND_CHILD_BLOCK_METADATA_DEFAULTS.icon,
-        compoundChildTitleJson: JSON.stringify(compoundChildTitle),
-        compoundPersistenceEnabled: compoundPersistenceEnabled ? "true" : "false",
-        projectToolsPackageVersion,
-        cssClassName,
-        dataStorageMode,
-        dashCase: slug,
-        description,
-        frontendCssClassName: buildFrontendCssClassName(cssClassName),
-        isAuthenticatedPersistencePolicy: persistencePolicy === "authenticated" ? "true" : "false",
-        isPublicPersistencePolicy: persistencePolicy === "public" ? "true" : "false",
-        bootstrapCredentialDeclarations: persistencePolicy === "public"
-            ? "publicWriteExpiresAt?: number & tags.Type< 'uint32' >;\n\tpublicWriteToken?: string & tags.MinLength< 1 > & tags.MaxLength< 512 >;"
-            : "restNonce?: string & tags.MinLength< 1 > & tags.MaxLength< 128 >;",
-        persistencePolicyDescriptionJson: JSON.stringify(persistencePolicy === "authenticated"
-            ? "Writes require a logged-in user and a valid REST nonce."
-            : "Anonymous writes use signed short-lived public tokens, per-request ids, and coarse rate limiting."),
-        keyword: slug.replace(/-/g, " "),
-        namespace,
-        needsMigration: "{{needsMigration}}",
-        pascalCase,
-        phpPrefix,
-        phpPrefixUpper,
-        restPackageVersion,
-        publicWriteRequestIdDeclaration: persistencePolicy === "public"
-            ? "publicWriteRequestId: string & tags.MinLength< 1 > & tags.MaxLength< 128 >;"
-            : "publicWriteRequestId?: string & tags.MinLength< 1 > & tags.MaxLength< 128 >;",
-        restWriteAuthIntent: persistencePolicy === "public"
-            ? "public-write-protected"
-            : "authenticated",
-        restWriteAuthMechanism: persistencePolicy === "public" ? "public-signed-token" : "rest-nonce",
-        restWriteAuthMode: persistencePolicy === "public" ? "public-signed-token" : "authenticated-rest-nonce",
-        slug,
-        slugCamelCase: pascalCase.charAt(0).toLowerCase() + pascalCase.slice(1),
-        slugKebabCase: slug,
-        slugSnakeCase,
-        textDomain,
-        textdomain: textDomain,
-        title,
-        titleJson: JSON.stringify(title),
-        titleCase: pascalCase,
-        persistencePolicy,
-    };
-}
 export async function scaffoldProject({ projectDir, templateId, answers, dataStorageMode, persistencePolicy, packageManager, externalLayerId, externalLayerSource, externalLayerSourceLabel, repositoryReference, cwd = process.cwd(), allowExistingDir = false, noInstall = false, installDependencies = undefined, variant, withMigrationUi = false, withTestPreset = false, withWpEnv = false, }) {
     const resolvedTemplateId = normalizeTemplateSelection(templateId);
     const resolvedPackageManager = getPackageManager(packageManager).id;

package/dist/runtime/template-defaults.d.ts

@@ -22,6 +22,10 @@ export declare const BUILTIN_TEMPLATE_METADATA_DEFAULTS: Readonly<{
         category: "widgets";
         icon: "screenoptions";
     }>;
+    "query-loop": Readonly<{
+        category: "widgets";
+        icon: "query-pagination";
+    }>;
 }>;
 /**
  * Shared hidden child block metadata defaults for compound scaffolds.
@@ -56,6 +60,9 @@ export declare function getBuiltInTemplateMetadataDefaults(templateId: keyof typ
 }> | Readonly<{
     category: "widgets";
     icon: "screenoptions";
+}> | Readonly<{
+    category: "widgets";
+    icon: "query-pagination";
 }>;
 /**
  * Checks whether a template id points at a removed built-in scaffold.

package/dist/runtime/template-defaults.js

@@ -22,6 +22,10 @@ export const BUILTIN_TEMPLATE_METADATA_DEFAULTS = Object.freeze({
         category: "widgets",
         icon: "screenoptions",
     }),
+    "query-loop": Object.freeze({
+        category: "widgets",
+        icon: "query-pagination",
+    }),
 });
 /**
  * Shared hidden child block metadata defaults for compound scaffolds.

package/dist/runtime/template-registry.d.ts

@@ -14,7 +14,7 @@ export declare const SHARED_MIGRATION_UI_TEMPLATE_ROOT: string;
 export declare const SHARED_WORKSPACE_TEMPLATE_ROOT: string;
 export declare const SHARED_TEST_PRESET_TEMPLATE_ROOT: string;
 export declare const SHARED_WP_ENV_PRESET_TEMPLATE_ROOT: string;
-export declare const BUILTIN_TEMPLATE_IDS: readonly ["basic", "interactivity", "persistence", "compound"];
+export declare const BUILTIN_TEMPLATE_IDS: readonly ["basic", "interactivity", "persistence", "compound", "query-loop"];
 export declare const OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE = "@wp-typia/create-workspace-template";
 export type BuiltInTemplateId = (typeof BUILTIN_TEMPLATE_IDS)[number];
 export type PersistencePolicy = "authenticated" | "public";

package/dist/runtime/template-registry.js

@@ -40,7 +40,13 @@ export const SHARED_MIGRATION_UI_TEMPLATE_ROOT = path.join(SHARED_TEMPLATE_ROOT,
 export const SHARED_WORKSPACE_TEMPLATE_ROOT = path.join(SHARED_TEMPLATE_ROOT, "workspace");
 export const SHARED_TEST_PRESET_TEMPLATE_ROOT = path.join(SHARED_PRESET_TEMPLATE_ROOT, "test-preset");
 export const SHARED_WP_ENV_PRESET_TEMPLATE_ROOT = path.join(SHARED_PRESET_TEMPLATE_ROOT, "wp-env");
-export const BUILTIN_TEMPLATE_IDS = ["basic", "interactivity", "persistence", "compound"];
+export const BUILTIN_TEMPLATE_IDS = [
+    "basic",
+    "interactivity",
+    "persistence",
+    "compound",
+    "query-loop",
+];
 export const OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE = "@wp-typia/create-workspace-template";
 export const TEMPLATE_REGISTRY = Object.freeze([
     {
@@ -71,6 +77,13 @@ export const TEMPLATE_REGISTRY = Object.freeze([
         features: ["InnerBlocks", "Hidden child blocks", "Optional persistence layer"],
         templateDir: path.join(TEMPLATE_ROOT, "compound"),
     },
+    {
+        id: "query-loop",
+        description: "A Query Loop block variation scaffold with stable namespace-based identity, inline starter layout, connected pattern presets, custom query seams, and runtime parity hooks",
+        defaultCategory: getBuiltInTemplateMetadataDefaults("query-loop").category,
+        features: ["core/query variation", "Default innerBlocks", "Connected patterns", "Custom query hooks", "Runtime parity hooks", "Allowed controls"],
+        templateDir: path.join(TEMPLATE_ROOT, "query-loop"),
+    },
     {
         id: OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE,
         description: "The official empty workspace template that powers `wp-typia add ...` workflows",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wp-typia/project-tools",
-  "version": "0.16.13",
+  "version": "0.17.0",
   "description": "Project orchestration and programmatic tooling for wp-typia",
   "packageManager": "bun@1.3.11",
   "type": "module",
@@ -120,8 +120,8 @@
   },
   "dependencies": {
     "@wp-typia/api-client": "^0.4.5",
-    "@wp-typia/block-runtime": "^0.4.9",
-    "@wp-typia/rest": "^0.3.9",
+    "@wp-typia/block-runtime": "^0.4.10",
+    "@wp-typia/rest": "^0.3.10",
     "@wp-typia/block-types": "^0.2.4",
     "mustache": "^4.2.0",
     "npm-package-arg": "^13.0.0",

package/templates/query-loop/inc/query-runtime.php.mustache

@@ -0,0 +1,85 @@
+<?php
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+function {{phpPrefix}}_get_query_loop_variation_name() {
+	return '{{namespace}}/{{slug}}';
+}
+
+function {{phpPrefix}}_get_query_loop_variation_marker_key() {
+	return 'wpTypiaVariation';
+}
+
+function {{phpPrefix}}_extract_query_loop_request_query( WP_REST_Request $request ) {
+	$params = $request->get_params();
+
+	if ( isset( $params['query'] ) && is_array( $params['query'] ) ) {
+		return $params['query'];
+	}
+
+	return is_array( $params ) ? $params : array();
+}
+
+function {{phpPrefix}}_map_query_loop_custom_query_vars( array $query_vars, array $source_query ) {
+	unset( $query_vars[ {{phpPrefix}}_get_query_loop_variation_marker_key() ] );
+
+	$allowed_custom_query_values = array(
+		// 'featuredOnly' => isset( $source_query['featuredOnly'] ) ? (bool) $source_query['featuredOnly'] : null,
+		// 'eventStatus' => isset( $source_query['eventStatus'] ) ? sanitize_text_field( $source_query['eventStatus'] ) : null,
+	);
+
+	// Mirror only known custom query keys from `src/query-extension.ts` here when
+	// they should affect frontend rendering or editor preview requests. Sanitize
+	// and cast values before copying them into WP_Query vars; do not merge the
+	// raw source query wholesale.
+	foreach ( $allowed_custom_query_values as $key => $value ) {
+		if ( null === $value ) {
+			continue;
+		}
+
+		$query_vars[ $key ] = $value;
+	}
+
+	return $query_vars;
+}
+
+function {{phpPrefix}}_filter_query_loop_block_query_vars( $query_vars, $block, $page ) {
+	if ( ! is_array( $query_vars ) ) {
+		return $query_vars;
+	}
+
+	$attrs = is_array( $block ) && isset( $block['attrs'] ) && is_array( $block['attrs'] )
+		? $block['attrs']
+		: array();
+	$namespace = isset( $attrs['namespace'] ) && is_string( $attrs['namespace'] )
+		? $attrs['namespace']
+		: null;
+	$source_query = isset( $attrs['query'] ) && is_array( $attrs['query'] )
+		? $attrs['query']
+		: array();
+
+	if ( {{phpPrefix}}_get_query_loop_variation_name() !== $namespace ) {
+		return $query_vars;
+	}
+
+	return {{phpPrefix}}_map_query_loop_custom_query_vars( $query_vars, $source_query );
+}
+
+function {{phpPrefix}}_filter_query_loop_editor_preview_query_vars( $query_vars, $request ) {
+	if ( ! is_array( $query_vars ) || ! $request instanceof WP_REST_Request ) {
+		return $query_vars;
+	}
+
+	$source_query = {{phpPrefix}}_extract_query_loop_request_query( $request );
+	$marker_key = {{phpPrefix}}_get_query_loop_variation_marker_key();
+	$variation_name = isset( $source_query[ $marker_key ] ) && is_string( $source_query[ $marker_key ] )
+		? $source_query[ $marker_key ]
+		: null;
+
+	if ( {{phpPrefix}}_get_query_loop_variation_name() !== $variation_name ) {
+		return $query_vars;
+	}
+
+	return {{phpPrefix}}_map_query_loop_custom_query_vars( $query_vars, $source_query );
+}

package/templates/query-loop/package.json.mustache

@@ -0,0 +1,32 @@
+{
+  "name": "{{slug}}",
+  "version": "0.1.0",
+  "packageManager": "bun@1.3.11",
+  "description": "{{description}}",
+  "author": "{{author}}",
+  "license": "GPL-2.0-or-later",
+  "main": "build/index.js",
+  "scripts": {
+    "build": "wp-scripts build --experimental-modules",
+    "start": "wp-scripts start --experimental-modules",
+    "dev": "wp-scripts start --experimental-modules",
+    "lint:js": "wp-scripts lint-js",
+    "lint": "bun run lint:js",
+    "format": "wp-scripts format",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@wp-typia/block-types": "{{blockTypesPackageVersion}}",
+    "@types/wordpress__block-editor": "^11.5.17",
+    "@types/wordpress__blocks": "^12.5.18",
+    "@wordpress/browserslist-config": "^6.42.0",
+    "@wordpress/scripts": "^30.22.0",
+    "eslint-plugin-jsx-a11y": "^6.10.2",
+    "prettier": "3.8.2",
+    "typescript": "^5.9.2"
+  },
+  "dependencies": {
+    "@wordpress/blocks": "^15.2.0",
+    "@wordpress/i18n": "^6.2.0"
+  }
+}