eddev 2.3.12 → 2.3.13

package/dist/node/utils/fs.d.ts

@@ -28,18 +28,23 @@ export declare const fs: {
         encoding: "buffer";
         withFileTypes?: false | undefined;
         recursive?: boolean | undefined;
-    } | "buffer"): Promise<Buffer[]>;
+    } | "buffer"): Promise<NonSharedBuffer[]>;
     readdir(path: import("fs").PathLike, options?: (import("fs").ObjectEncodingOptions & {
         withFileTypes?: false | undefined;
         recursive?: boolean | undefined;
-    }) | BufferEncoding | null): Promise<string[] | Buffer[]>;
+    }) | BufferEncoding | null): Promise<string[] | NonSharedBuffer[]>;
     readdir(path: import("fs").PathLike, options: import("fs").ObjectEncodingOptions & {
         withFileTypes: true;
         recursive?: boolean | undefined;
     }): Promise<import("fs").Dirent[]>;
+    readdir(path: import("fs").PathLike, options: {
+        encoding: "buffer";
+        withFileTypes: true;
+        recursive?: boolean | undefined;
+    }): Promise<import("fs").Dirent<NonSharedBuffer>[]>;
     readlink(path: import("fs").PathLike, options?: import("fs").ObjectEncodingOptions | BufferEncoding | null): Promise<string>;
-    readlink(path: import("fs").PathLike, options: import("fs").BufferEncodingOption): Promise<Buffer>;
-    readlink(path: import("fs").PathLike, options?: import("fs").ObjectEncodingOptions | string | null): Promise<string | Buffer>;
+    readlink(path: import("fs").PathLike, options: import("fs").BufferEncodingOption): Promise<NonSharedBuffer>;
+    readlink(path: import("fs").PathLike, options?: import("fs").ObjectEncodingOptions | string | null): Promise<string | NonSharedBuffer>;
     symlink(target: import("fs").PathLike, path: import("fs").PathLike, type?: string | null): Promise<void>;
     lstat(path: import("fs").PathLike, opts?: import("fs").StatOptions & {
         bigint?: false | undefined;
@@ -71,11 +76,11 @@ export declare const fs: {
     chown(path: import("fs").PathLike, uid: number, gid: number): Promise<void>;
     utimes(path: import("fs").PathLike, atime: import("fs").TimeLike, mtime: import("fs").TimeLike): Promise<void>;
     realpath(path: import("fs").PathLike, options?: import("fs").ObjectEncodingOptions | BufferEncoding | null): Promise<string>;
-    realpath(path: import("fs").PathLike, options: import("fs").BufferEncodingOption): Promise<Buffer>;
-    realpath(path: import("fs").PathLike, options?: import("fs").ObjectEncodingOptions | BufferEncoding | null): Promise<string | Buffer>;
+    realpath(path: import("fs").PathLike, options: import("fs").BufferEncodingOption): Promise<NonSharedBuffer>;
+    realpath(path: import("fs").PathLike, options?: import("fs").ObjectEncodingOptions | BufferEncoding | null): Promise<string | NonSharedBuffer>;
     mkdtemp(prefix: string, options?: import("fs").ObjectEncodingOptions | BufferEncoding | null): Promise<string>;
-    mkdtemp(prefix: string, options: import("fs").BufferEncodingOption): Promise<Buffer>;
-    mkdtemp(prefix: string, options?: import("fs").ObjectEncodingOptions | BufferEncoding | null): Promise<string | Buffer>;
+    mkdtemp(prefix: string, options: import("fs").BufferEncodingOption): Promise<NonSharedBuffer>;
+    mkdtemp(prefix: string, options?: import("fs").ObjectEncodingOptions | BufferEncoding | null): Promise<string | NonSharedBuffer>;
     writeFile(file: import("fs").PathLike | nodeFs.FileHandle, data: string | NodeJS.ArrayBufferView | Iterable<string | NodeJS.ArrayBufferView> | AsyncIterable<string | NodeJS.ArrayBufferView> | import("stream"), options?: (import("fs").ObjectEncodingOptions & {
         mode?: import("fs").Mode | undefined;
         flag?: import("fs").OpenMode | undefined;
@@ -87,25 +92,23 @@ export declare const fs: {
     readFile(path: import("fs").PathLike | nodeFs.FileHandle, options?: ({
         encoding?: null | undefined;
         flag?: import("fs").OpenMode | undefined;
-    } & import("events").Abortable) | null): Promise<Buffer>;
+    } & import("events").Abortable) | null): Promise<NonSharedBuffer>;
     readFile(path: import("fs").PathLike | nodeFs.FileHandle, options: ({
         encoding: BufferEncoding;
         flag?: import("fs").OpenMode | undefined;
     } & import("events").Abortable) | BufferEncoding): Promise<string>;
     readFile(path: import("fs").PathLike | nodeFs.FileHandle, options?: (import("fs").ObjectEncodingOptions & import("events").Abortable & {
         flag?: import("fs").OpenMode | undefined;
-    }) | BufferEncoding | null): Promise<string | Buffer>;
+    }) | BufferEncoding | null): Promise<string | NonSharedBuffer>;
     opendir(path: import("fs").PathLike, options?: import("fs").OpenDirOptions): Promise<import("fs").Dir>;
-    watch(filename: import("fs").PathLike, options: (import("fs").WatchOptions & {
-        encoding: "buffer";
-    }) | "buffer"): AsyncIterable<nodeFs.FileChangeInfo<Buffer>>;
-    watch(filename: import("fs").PathLike, options?: import("fs").WatchOptions | BufferEncoding): AsyncIterable<nodeFs.FileChangeInfo<string>>;
-    watch(filename: import("fs").PathLike, options: import("fs").WatchOptions | string): AsyncIterable<nodeFs.FileChangeInfo<string>> | AsyncIterable<nodeFs.FileChangeInfo<Buffer>>;
+    watch(filename: import("fs").PathLike, options?: nodeFs.WatchOptionsWithStringEncoding | BufferEncoding): NodeJS.AsyncIterator<nodeFs.FileChangeInfo<string>>;
+    watch(filename: import("fs").PathLike, options: nodeFs.WatchOptionsWithBufferEncoding | "buffer"): NodeJS.AsyncIterator<nodeFs.FileChangeInfo<NonSharedBuffer>>;
+    watch(filename: import("fs").PathLike, options: nodeFs.WatchOptions | BufferEncoding | "buffer"): NodeJS.AsyncIterator<nodeFs.FileChangeInfo<string | NonSharedBuffer>>;
     cp(source: string | URL, destination: string | URL, opts?: import("fs").CopyOptions): Promise<void>;
-    glob(pattern: string | string[]): NodeJS.AsyncIterator<string>;
-    glob(pattern: string | string[], opt: import("fs").GlobOptionsWithFileTypes): NodeJS.AsyncIterator<import("fs").Dirent>;
-    glob(pattern: string | string[], opt: import("fs").GlobOptionsWithoutFileTypes): NodeJS.AsyncIterator<string>;
-    glob(pattern: string | string[], opt: import("fs").GlobOptions): NodeJS.AsyncIterator<import("fs").Dirent | string>;
+    glob(pattern: string | readonly string[]): NodeJS.AsyncIterator<string>;
+    glob(pattern: string | readonly string[], options: import("fs").GlobOptionsWithFileTypes): NodeJS.AsyncIterator<import("fs").Dirent>;
+    glob(pattern: string | readonly string[], options: import("fs").GlobOptionsWithoutFileTypes): NodeJS.AsyncIterator<string>;
+    glob(pattern: string | readonly string[], options: import("fs").GlobOptions): NodeJS.AsyncIterator<import("fs").Dirent | string>;
     constants: typeof import("fs").constants;
 };
 //# sourceMappingURL=fs.d.ts.map

package/dist/node/utils/fs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../../src/node/utils/fs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AAGrC,eAAO,MAAM,EAAE;6BAEkB,MAAM,WAAW,MAAM;iCAWnB,MAAM,WAAW,GAAG;sBAW/B,MAAM,WAAW,GAAG;qBAGrB,MAAM;mBAIR,MAAM;mBAQN,MAAM;;;;;;;;;;;;iBAQgw0B,CAAC;;;;qBAAqkD,CAAC;iBAA8C,CAAC;;;;qBAAmjB,CAAC;iBAA8C,CAAC;;;qBAA+gB,CAAC;iBAA8C,CAAC;;;;iBAAkhB,CAAC;;;;;;;cAA65F,CAAC;;;;;;;cAAoe,CAAC;;;;;;;cAAif,CAAC;;;;;;;;;;;;;;;;;;;;;YAAkoT,CAAC;YAAwC,CAAC;aAAoR,CAAC;;;aAAi2B,CAAC;;;gBAAosE,CAAC;YAAwC,CAAC;;;;YAA4nB,CAAC;;;YAAwrB,CAAC;;;;;;;;;;;;;;CADnw/C,CAAA"}
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../../src/node/utils/fs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AAGrC,eAAO,MAAM,EAAE;6BAEkB,MAAM,WAAW,MAAM;iCAWnB,MAAM,WAAW,GAAG;sBAW/B,MAAM,WAAW,GAAG;qBAGrB,MAAM;mBAIR,MAAM;mBAQN,MAAM;;;;;;;;;;;;iBAQs+0B,CAAC;;;;qBAAqkD,CAAC;iBAA8C,CAAC;;;;qBAAmjB,CAAC;iBAA8C,CAAC;;;qBAAwhB,CAAC;iBAA8C,CAAC;;;;iBAA2hB,CAAC;;;;;iBAA2c,CAAC;;;;;;;cAAu9F,CAAC;;;;;;;cAAoe,CAAC;;;;;;;cAAif,CAAC;;;;;;;;;;;;;;;;;;;;;YAA6rT,CAAC;YAAwC,CAAC;aAAoR,CAAC;;;aAAi2B,CAAC;;;gBAAosE,CAAC;YAAwC,CAAC;;;;YAAqoB,CAAC;;;YAAwrB,CAAC;;;;;;;;;;;;CADrkhD,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eddev",
-  "version": "2.3.12",
+  "version": "2.3.13",
   "description": "",
   "main": "index.js",
   "type": "module",
@@ -133,7 +133,7 @@
     "undent": "^0.1.0",
     "undici": "6.21.0",
     "valtio": "^2.3.1",
-    "vinxi": "^0.5.8",
+    "vinxi": "0.5.11",
     "vite-plugin-glsl": "^1.5.5",
     "vite-tsconfig-paths": "4.3.2",
     "zod": "^4.1.12"

package/skills/eddev/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: eddev
+description: Work on ED.'s eddev WordPress + React/TypeScript stack. Use when you need to build, maintain, modify, debug, explain, or document eddev themes, including WordPress route resolution, React views and blocks, GraphQL data files, generated query hooks, ACF, serverless/RPC routes, SPA mode, SSR mode, the eddev CLI, and project conventions.
+---
+
+# eddev
+
+eddev is ED.'s stack for building WordPress-backed websites with React, TypeScript, GraphQL, and serverless rendering. Treat WordPress as the CMS and routing authority: WordPress resolves the requested URL, builds the route payload, and decides which React view should render. The React app renders that payload in either WordPress-hosted SPA mode or serverless SSR mode.
+
+Use this skill to keep eddev work aligned with the real stack rather than generic WordPress, generic React, or generic Next.js assumptions.
+
+## Best Practice
+
+- Preserve WordPress as the source of truth for routes, content editing, admin state, custom post types, ACF fields, and route payloads.
+- Keep React responsible for rendering views, blocks, app shell UI, interactive components, and project-specific frontend behavior.
+- Use GraphQL files to select data. Do not imply ACF fields or WordPress objects are passed directly to components without a query layer.
+- Prefer existing eddev APIs and project conventions before inventing abstractions.
+- Keep examples type-safe and source-backed. Use generated types and generated query hooks when docs or project code expose them.
+- Separate route/render data from runtime browser data. View, block, and app GraphQL files support route rendering; `queries/*.graphql` files support generated runtime hooks.
+- Route runtime GraphQL through named REST endpoints and generated hooks. Do not describe eddev as exposing arbitrary public GraphQL text posts from the browser.
+- Use serverless/RPC routes for backend TypeScript procedures that belong in `server/routes/**/*.{ts,tsx}`.
+- Keep docs and explanations practical for ED developers. Prefer direct file paths, workflow steps, and small representative examples.
+
+## Stack Basics
+
+The normal eddev project combines:
+
+- WordPress and PHP for routing, admin, content editing, custom post types, ACF, REST endpoints, and route payload generation.
+- React and TypeScript for views, blocks, app layout, interactive UI, and server routes.
+- GraphQL and WPGraphQL for view data, block props, app shell data, fragments, runtime queries, and runtime mutations.
+- The eddev CLI for discovering files, generating TypeScript outputs, running development servers, and building SPA or serverless output.
+- Local for local WordPress development, WP Engine for the WordPress origin, and Vercel or another serverless target for public SSR traffic.
+
+The key request flow is:
+
+1. WordPress resolves the URL through the normal template hierarchy.
+2. eddev maps the resolved template to a React view in `views/`.
+3. eddev runs the paired view GraphQL file when one exists.
+4. WordPress returns a route payload containing the matched view, `viewData`, app data, metadata, admin context, and debug data when available.
+5. In SSR mode, the JavaScript server renders the matching React view to HTML and hydrates in the browser.
+6. In SPA mode, WordPress serves the app shell and payload, then the browser renders the view client-side.
+
+Blocks follow the same split: WordPress and ACF own editor data, `blocks/**/*.graphql` selects the public props, and React block components render the frontend output.
+
+## Common File Conventions
+
+- `views/*.tsx` defines React views, usually with `defineView("name", component)`.
+- `views/*.graphql` selects data for the paired view.
+- `views/_app.tsx` defines the shared app shell.
+- `views/_app.graphql` selects global app data.
+- `blocks/**/*.tsx` defines React blocks, usually with `export const meta: BlockMeta` and `defineBlock("folder/name", component)`.
+- `blocks/**/*.graphql` selects public block props from WordPress and ACF data.
+- `queries/fragments/*.graphql` contains reusable GraphQL fragments.
+- `queries/*.graphql` creates generated runtime query or mutation hooks.
+- `server/routes/**/*.{ts,tsx}` defines TypeScript RPC/serverless procedures through `eddev/server`.
+- `ed.config.json` configures project-level eddev behavior.
+
+## Referring To The Docs
+
+Use the synced docs in this skill before answering detailed eddev questions. Start with the table of contents below, then read only the relevant `.mdx` files needed for the user's task.
+
+- For the high-level model, read `docs/stack/overview.mdx`, `docs/stack/how-it-works.mdx`, and `docs/stack/spa-vs-ssr.mdx`.
+- For project setup and commands, read `docs/getting-started.mdx`, `docs/software.mdx`, and `docs/devtool/cli.mdx`.
+- For routing, read `docs/routing.mdx` and the nested routing pages.
+- For data work, read `docs/graphql.mdx` and the matching nested page for fragments, query hooks, mutation hooks, infinite queries, global data, tooling, or schema extensions.
+- For page templates, read `docs/views.mdx` and the nested views pages.
+- For Gutenberg blocks, read `docs/blocks/overview.mdx` and the nested blocks pages.
+- For ACF, read `docs/acf.mdx` and the nested ACF pages.
+- For serverless behavior, read `docs/serverless.mdx` and `docs/serverless/functions.mdx`.
+- For quick implementation patterns, read the relevant page under `docs/snippets/`.
+
+When writing docs or code comments, cite the public docs path in prose, such as `/docs/graphql/query-hooks`, rather than exposing this skill folder path to readers.
+
+Do not hand-edit the generated contents block below. `scripts/update-skill.js` keeps it synced from `skills/eddev/index.mdx`.
+
+<!-- START TOC -->
+
+- Stack
+  - [Overview](docs/stack/overview.mdx): Understand the main technologies and hosting shape behind eddev sites.
+  - [How It Works](docs/stack/how-it-works.mdx): Follow the end-to-end request flow for an eddev page.
+  - [SPA vs SSR](docs/stack/spa-vs-ssr.mdx): Compare WordPress-hosted SPA mode with serverless SSR mode.
+- [Software and Tooling](docs/software.mdx): Tools we use to build, edit, and run eddev projects.
+
+- **Guides**
+- [Getting Started](docs/getting-started.mdx): Set up a new eddev project from the starter theme.
+- Dev Tools
+  - [eddev CLI](docs/devtool/cli.mdx): Run development, builds, codegen, and diagnostics through the eddev CLI.
+  - [Dev Overlay](docs/devtool/overlay.mdx): Use the in-browser development overlay while working on eddev sites.
+- Infrastructure
+  - [Deployment](docs/infra/deployment.mdx): A placeholder for deployment workflows across GitHub, Vercel, and Cloudflare.
+  - [Local](docs/infra/local.mdx): A placeholder for Local setup and push-pull workflow guidance.
+  - [Security](docs/infra/security.mdx): A placeholder for origin protection and secret management guidance.
+  - [Caching](docs/infra/caching.mdx): A placeholder for eddev cache configuration and deployment layers.
+- Design System
+  - [Colours](docs/design/color.mdx): Configure colour tokens and Figma handoff output for Tailwind.
+  - [Typography](docs/design/type.mdx): Configure typography tokens through Tailwind helper classes.
+  - [Using Icons](docs/design/icons.mdx): Export and use Figma icons as React-friendly SVG components.
+  - [Grid System](docs/design/grid.mdx): Configure grid tokens, gutters, and layout utilities.
+  - [Responsive Scaling](docs/design/responsive-scaling.mdx): Configure responsive Tailwind tokens with the local helper.
+  - [Favicons](docs/design/favicons.mdx): Configure how eddev generates or delegates favicon assets.
+- More Guides
+  - [Colour Schemes](docs/guides/color-schemes.mdx): Define named visual schemes with Tailwind semantic tokens.
+  - [Integrations](docs/guides/integrations.mdx): A placeholder for third-party integration guidance.
+  - [Page Transitions](docs/guides/page-transitions.mdx): A placeholder for page transition patterns in eddev sites.
+  - [SEO](docs/guides/seo.mdx): A placeholder for SEO patterns in eddev sites.
+  - [State Management](docs/guides/state-management.mdx): A placeholder for state management guidance in eddev sites.
+- Snippets
+  - [Overview](docs/snippets.mdx): Situation-based recipes from real eddev themes
+  - [Querying Specific Blocks](docs/snippets/querying-specific-blocks.mdx): Select, split, and render only the block content you need
+  - [Type-Safe ACF Dropdowns](docs/snippets/type-safe-acf-dropdowns.mdx): Register one enum field and use its generated TypeScript type
+  - [Multiple Editable Zones](docs/snippets/multiple-editable-zones.mdx): Use SlotBlocks when one block needs more than one child area
+  - [Automated Block Layouts](docs/snippets/automated-block-layouts.mdx): Use block flags and wrapBlock to keep layout rules out of every block
+  - [Submitting Forms To RPC](docs/snippets/submitting-forms-to-rpc.mdx): Create a serverless mutation and call it from React
+  - [Custom Routes And URLs](docs/snippets/custom-routes-and-urls.mdx): Map fixed URLs to views and keep generated WordPress links aligned
+  - [SVGs](docs/snippets/svgs.mdx): Copy/paste SVG upload and GraphQL snippets
+
+- **Components**
+- [Configuration](docs/config.mdx): Configure eddev projects with theme-level JSON settings.
+- Routing
+  - [Routing Overview](docs/routing.mdx): Understand the WordPress and frontend sides of eddev routing.
+  - [Custom Routes](docs/routing/custom.mdx): Register fixed WordPress-backed routes for app-like screens.
+  - [WordPress Routing](docs/routing/wordpress.mdx): Let WordPress resolve URLs while React renders the matched view.
+  - [Frontend Routing APIs](docs/routing/api.mdx): Use eddev routing APIs for links, preloading, and client navigation.
+  - [How it Works](docs/routing/full-details.mdx): Trace how eddev loads route data for SPA and serverless navigation.
+- GraphQL
+  - [Overview](docs/graphql.mdx): Working with GraphQL in eddev
+  - [Global Data](docs/graphql/global-data.mdx): Fetch shared site shell data through views/_app.graphql.
+  - [GraphQL Fragments](docs/graphql/fragments.mdx): Share GraphQL selections and generated fragment types across queries.
+  - [Query Hooks](docs/graphql/query-hooks.mdx): Generate browser runtime query hooks from files in queries.
+  - [Mutation Hooks](docs/graphql/mutation-hooks.mdx): Generate mutation hooks for runtime GraphQL operations with side effects.
+  - [Infinite Queries](docs/graphql/infinite-queries.mdx): Build load-more interfaces with generated infinite query hooks.
+  - [Extending the GraphQL Schema](docs/graphql/extending.mdx): Extend WPGraphQL when frontend data needs custom schema fields.
+  - [GraphQL Tooling](docs/graphql/tooling.mdx): Use generated schema files with editor tooling and GraphiQL.
+- Views
+  - [Views](docs/views.mdx): Page and post-type templates
+  - [_app.tsx Layout](docs/views/app-view.mdx): Common site layout
+  - [Page Templates](docs/views/page-templates.mdx): Selectable templates for pages and post types
+  - [View Data](docs/views/queries.mdx): Pipe WordPress data into your templates
+- Blocks
+  - [Overview](docs/blocks/overview.mdx): The basics of creating Gutenberg blocks
+  - [Defining a block](docs/blocks/block-definition.mdx): How to create a new block type
+  - [Data and Editing](docs/blocks/data-and-editing.mdx): GraphQL props, inline content, and core block rendering
+  - [Configuring the Editor](docs/blocks/editor-config.mdx): Control which blocks authors can use
+  - [Nested Blocks](docs/blocks/nested-blocks.mdx): Blocks within blocks
+  - [Template Parts](docs/blocks/template-parts.mdx): Reusable site sections powered by blocks
+  - [Core Blocks](docs/blocks/core-blocks.mdx): Working with WordPress core blocks in eddev
+- ACF
+  - [ACF](docs/acf.mdx): Custom ACF fields, enum field shortcuts, and React widgets for WordPress admin screens.
+  - [Custom Fields](docs/acf/custom-fields.mdx): Build a custom ACF field type with PHP storage and React editing UI.
+  - [Custom Enums](docs/acf/custom-enums.mdx): Register reusable typed ACF choice fields without writing a full custom field UI.
+  - [Admin Panel Widgets](docs/acf/admin-panel-widgets.mdx): Mount React widgets inside custom WordPress admin pages.
+- Serverless
+  - [Serverless](docs/serverless.mdx): Run the public eddev frontend on Vercel while WordPress owns content and routing.
+  - [RPC Functions](docs/serverless/functions.mdx): Define TypeScript RPC routes for serverless eddev projects.
+
+<!-- END TOC -->

package/skills/eddev/docs/acf/admin-panel-widgets.mdx

@@ -0,0 +1,99 @@
+# Admin Panel Widgets (/docs/acf/admin-panel-widgets)
+
+**Mount React widgets inside custom WordPress admin pages.**
+
+Admin panel widgets are not ACF fields. They are React components mounted into WordPress admin screens, useful for project tools such as sync panels, importers, reports, or asset managers.
+
+The SFF site uses this pattern for festival sync tooling and film asset management. The reusable shape is simpler than those production tools: create a widget TSX file, print a matching `data-widget` element from PHP, and enable the eddev admin assets on that screen.
+
+## Create The Widget [#create-the-widget]
+
+Widget files live in `backend/widgets/*.tsx`. The file slug is what PHP uses in `data-widget`.
+
+```tsx filename="backend/widgets/content-sync.tsx"
+import { defineWidget } from "eddev/admin"
+import { useState } from "react"
+
+export default defineWidget("content-sync", () => {
+  const [message, setMessage] = useState<string | null>(null)
+  const [busy, setBusy] = useState(false)
+
+  async function runSync() {
+    setBusy(true)
+    setMessage(null)
+
+    const response = await fetch("/wp-json/site/v1/sync-content", {
+      method: "POST",
+    })
+
+    setBusy(false)
+    setMessage(response.ok ? "Sync complete." : "Sync failed.")
+  }
+
+  return (
+    <div className="postbox p-4">
+      <p>Run the latest content sync.</p>
+      <button className="button button-primary" disabled={busy} onClick={runSync}>
+        {busy ? "Syncing..." : "Run sync"}
+      </button>
+      {message && <p>{message}</p>}
+    </div>
+  )
+})
+```
+
+Keep the `defineWidget` name and the filename slug the same. eddev discovers the file from `backend/widgets/content-sync.tsx`, and the admin page mounts it with `data-widget="content-sync"`.
+
+## Add A WordPress Admin Page [#add-a-wordpress-admin-page]
+
+The PHP side can live wherever your backend include file loads project systems. Large sites often keep this near the system it controls, for example under `backend/systems/*/*.php`.
+
+```php filename="backend/systems/content-sync/content-sync-admin.php"
+<?php
+
+use ED\AdminAssets;
+
+add_action("admin_menu", function () {
+  add_menu_page(
+    "Content Sync",
+    "Content Sync",
+    "edit_theme_options",
+    "content-sync",
+    "showContentSyncAdminPage",
+    "dashicons-update",
+    31
+  );
+
+  add_filter("ed_should_enqueue_admin_scripts", function ($enabled, $screen) {
+    if ($screen->id === "toplevel_page_content-sync") {
+      return true;
+    }
+
+    return $enabled;
+  }, 10, 2);
+});
+
+function showContentSyncAdminPage() {
+  AdminAssets::$enabled = true;
+  ?>
+  <div class="wrap">
+    <h1 class="wp-heading-inline">Content Sync</h1>
+    <div data-widget="content-sync"></div>
+  </div>
+  <?php
+}
+```
+
+`AdminAssets` loads the eddev admin bundle. The widget runner scans the page for `[data-widget]` elements and mounts the matching React widget.
+
+## Data Access [#data-access]
+
+Widgets can call normal WordPress REST endpoints with `fetch`. They can also use generated query hooks when the data is exposed through committed `queries/**/*.graphql` files.
+
+Use a widget when the screen is an operational tool rather than page content. For example:
+
+* a sync panel that starts a background import and reports progress
+* an asset manager that lets editors inspect and update media for a post type
+* a small admin dashboard that combines project-specific status checks
+
+If the UI is meant to edit a single ACF value inside a field group, build a [custom field](/docs/acf/custom-fields) instead.

package/skills/eddev/docs/acf/custom-enums.mdx

@@ -0,0 +1,75 @@
+# Custom Enums (/docs/acf/custom-enums)
+
+**Register reusable typed ACF choice fields without writing a full custom field UI.**
+
+Custom enums are shorthand for semi-custom ACF fields. They create a named ACF field type backed by a normal ACF choice control, then expose that value to GraphQL as a generated TypeScript-friendly scalar.
+
+Use them for repeated dropdowns like colour schemes, content tones, states, categories, or display modes.
+
+## Register An Enum Field [#register-an-enum-field]
+
+Put enum registrations in `backend/fields/*.php`.
+
+```php filename="backend/fields/content-tone.php"
+<?php
+
+ED()->registerEnumFieldType("content-tone", [
+  "label" => "Content Tone",
+  "type" => "select",
+  "options" => [
+    "neutral" => "Neutral",
+    "festival" => "Festival",
+    "urgent" => "Urgent",
+  ],
+]);
+```
+
+The enum field type slug is `content-tone`. Add that field type to any ACF field group where authors should choose one of those values.
+
+`type` controls the underlying ACF editing control:
+
+| Type           | Use It For                                                   |
+| -------------- | ------------------------------------------------------------ |
+| `select`       | The default choice for most dropdowns.                       |
+| `button_group` | Short visual choices with only a few options.                |
+| `radio`        | Choices that should stay visible without opening a dropdown. |
+| `checkbox`     | Multiple selected values.                                    |
+
+`checkbox` returns a list of enum values in GraphQL. The other types return one value or `null`.
+
+## Query The Field [#query-the-field]
+
+Once the field has been added to ACF, select it from the relevant view or block query.
+
+```graphql filename="blocks/content/callout.graphql"
+query {
+  block {
+    content_callout {
+      tone
+    }
+  }
+}
+```
+
+eddev derives the generated type name from the field slug. `content-tone` becomes `ContentToneOption`.
+
+```tsx filename="blocks/content/callout.tsx"
+import { defineBlock } from "eddev/blocks"
+import type { ContentToneOption } from "@generated-types"
+
+const toneClasses: Record<ContentToneOption, string> = {
+  neutral: "theme-neutral",
+  festival: "theme-festival",
+  urgent: "theme-urgent",
+}
+
+export default defineBlock("content/callout", (props) => {
+  const tone = props.tone ?? "neutral"
+
+  return <section className={toneClasses[tone]}>...</section>
+})
+```
+
+Keep the PHP options and React mapping together during review. If a new enum option is added, TypeScript should force the component to decide how that option renders.
+
+For a more recipe-style dropdown example, see [Type-Safe ACF Dropdowns](/docs/snippets/type-safe-acf-dropdowns).

package/skills/eddev/docs/acf/custom-fields.mdx

@@ -0,0 +1,131 @@
+# Custom Fields (/docs/acf/custom-fields)
+
+**Build a custom ACF field type with PHP storage and React editing UI.**
+
+Custom fields are for reusable editor controls that need more than a built-in ACF input. A field has two sides:
+
+* a PHP file that registers the ACF field type and its GraphQL shape
+* a React file that renders the editing control in WordPress admin
+
+Put both files in `backend/fields` and keep the slug consistent across the PHP registration, the TSX filename, and the ACF field type.
+
+## Register The PHP Field [#register-the-php-field]
+
+The PHP file is loaded by the backend include path. Starter themes include `backend/fields/*.php` from `backend/includes.php`.
+
+```php filename="backend/fields/event-link.php"
+<?php
+
+ED()->registerFieldType("event-link", [
+  "label" => "Event Link",
+  "type" => "EventLink",
+  "objectType" => [
+    "fields" => [
+      "label" => ["type" => "String"],
+      "url" => ["type" => "String"],
+      "opensInNewTab" => ["type" => "Boolean"],
+    ],
+  ],
+  "resolve" => function ($root, $args, $context, $info, $value) {
+    return is_array($value) ? $value : null;
+  },
+]);
+```
+
+`registerFieldType` makes `event-link` available as an ACF field type. The `type` value is the GraphQL type returned when a GraphQL file selects this field.
+
+Use `objectType` for small structured values. For richer project data, register GraphQL types and resolvers explicitly, then set `type` to the GraphQL type name.
+
+## Add The React Editor [#add-the-react-editor]
+
+The React file is discovered by eddev's admin manifest from `backend/fields/*.tsx`. Its filename must match the ACF field type slug.
+
+```tsx filename="backend/fields/event-link.tsx"
+import { defineField } from "eddev/admin"
+
+type EventLinkValue = {
+  label?: string
+  url?: string
+  opensInNewTab?: boolean
+}
+
+export default defineField<EventLinkValue>({
+  defaultValue: {},
+  render({ value, onChange }) {
+    return (
+      <div className="stack-y-2">
+        <label>
+          <span>Label</span>
+          <input
+            className="regular-text"
+            value={value.label ?? ""}
+            onChange={(event) => {
+              onChange({ ...value, label: event.target.value })
+            }}
+          />
+        </label>
+
+        <label>
+          <span>URL</span>
+          <input
+            className="regular-text"
+            value={value.url ?? ""}
+            onChange={(event) => {
+              onChange({ ...value, url: event.target.value })
+            }}
+          />
+        </label>
+
+        <label>
+          <input
+            type="checkbox"
+            checked={!!value.opensInNewTab}
+            onChange={(event) => {
+              onChange({ ...value, opensInNewTab: event.target.checked })
+            }}
+          />
+          Open in a new tab
+        </label>
+      </div>
+    )
+  },
+})
+```
+
+`defineField` receives the current value and an `onChange` callback. eddev stores the React value in ACF through a hidden JSON input, then the PHP side can normalize or resolve it for GraphQL.
+
+## Use The Field In ACF [#use-the-field-in-acf]
+
+After the PHP field type is registered, add it to a field group in ACF like any other field type. The field can live on a block, post type, options page, taxonomy, or other ACF location.
+
+When a block or view selects that field, GraphQL receives the resolved value:
+
+```graphql filename="blocks/content/event-card.graphql"
+query {
+  block {
+    content_event_card {
+      cta {
+        label
+        url
+        opensInNewTab
+      }
+    }
+  }
+}
+```
+
+```tsx filename="blocks/content/event-card.tsx"
+import { defineBlock } from "eddev/blocks"
+
+export default defineBlock("content/event-card", (props) => {
+  if (!props.cta?.url) return null
+
+  return (
+    <a href={props.cta.url} target={props.cta.opensInNewTab ? "_blank" : undefined}>
+      {props.cta.label ?? "Read more"}
+    </a>
+  )
+})
+```
+
+Keep custom fields focused. If the editor only needs a fixed list of choices, use a [custom enum field](/docs/acf/custom-enums) instead.

package/skills/eddev/docs/acf.mdx

@@ -0,0 +1,31 @@
+# ACF (/docs/acf)
+
+**Custom ACF fields, enum field shortcuts, and React widgets for WordPress admin screens.**
+
+Use this section when normal ACF fields are not enough for a site-specific editing workflow.
+
+Most day-to-day block and view data should still use ordinary ACF fields selected through GraphQL. Reach for these tools when the editor needs a reusable control, a typed dropdown used across field groups, or a custom admin screen that runs React.
+
+<Cards>
+  <Card title="Custom Fields" href="/docs/acf/custom-fields">
+    Pair a PHP field registration with a React editor control in `backend/fields`.
+  </Card>
+
+  <Card title="Custom Enums" href="/docs/acf/custom-enums">
+    Register a typed select, radio, button group, or checkbox field without writing React.
+  </Card>
+
+  <Card title="Admin Panel Widgets" href="/docs/acf/admin-panel-widgets">
+    Mount React widgets inside custom WordPress admin pages.
+  </Card>
+</Cards>
+
+## Which Tool To Use [#which-tool-to-use]
+
+| Need                                                           | Use                                                  |
+| -------------------------------------------------------------- | ---------------------------------------------------- |
+| A field with custom React editing UI and custom GraphQL output | [Custom Fields](/docs/acf/custom-fields)             |
+| A reusable typed dropdown or button group                      | [Custom Enums](/docs/acf/custom-enums)               |
+| A custom admin screen, importer, sync tool, or asset manager   | [Admin Panel Widgets](/docs/acf/admin-panel-widgets) |
+
+Custom fields and enums are still ACF field types. Admin panel widgets are separate from ACF, but they use the same eddev admin bundle and are useful for adjacent WordPress editing tools.