About This Theme

Repository Model

• This suite repo contains the theme plus installable plugins.
• New client repos are typically theme-focused and can exclude plugin source packages.
• Plugin functionality is added per client by uploading plugin zips.

Theme-Only Workflow

• Work in examples/ and example-parts/ for MLS wiring/reference implementations.
• Keep templates/ and template-parts/ focused on runtime shared/global theme behavior only.
• Keep styling in Tailwind-driven theme assets and avoid ad-hoc CSS drift.
• Use reusable sections/components where possible for long-term maintainability.

Tailwind In This Theme

• Tailwind version is 4.2.x (root toolchain).
• Tailwind is compiled from repo-level source files:
• build/tailwind/tailwind.css
• build/tailwind/critical.css
• Entry files use Tailwind v4 syntax:
• @import "tailwindcss" source(none);
• @config "../../tailwind.config.js";
• @source ... directives for theme PHP/HTML/JS scanning
• Tailwind config lives at repo root: tailwind.config.js.
• Build outputs are written to theme assets:
• packages/asnet-core-theme/assets/css/tailwind.css
• packages/asnet-core-theme/assets/css/critical-tailwind.css
• Runtime loading is handled by:
• packages/asnet-core-theme/template-parts/themecore-styles.php
• Practical workflow:
• Edit markup/classes in theme templates, examples, and parts.
• Rebuild with npx gulp tailwind (or use npx gulp watch).
• Do not hand-edit compiled CSS outputs in assets/css/.
• Intent:
• Use utility classes for most layout/spacing/typography.
• Keep custom CSS small and intentional when utilities are not enough.

Gutenberg Policy (Client-Level In Theme)

• Block filtering belongs in theme, not DevCore, so each client can define editorial scope.
• Theme now enforces a starter allowlist for non-power users on post and page.
• No capability bypass is enabled by default; allowlist applies to all users unless a client override adds bypass caps.
• Any registered ASNET block namespace is auto-allowed in restricted editors.
• Embed options are intentionally limited to Embed, YouTube, and Vimeo.
• Three starter responsive patterns are provided for non-power users:
• Image Left + Text
• Image Right + Text
• Feature Image + Body

MLS Block Ownership

• MLS content blocks are plugin-owned.
• Current vessel blocks in the inserter are registered by asnet-iyba-plugin.
• If the IYBA plugin is inactive, those IYBA blocks are unavailable.
• Theme policy only controls allowed/visible blocks; it does not register MLS blocks itself.

Per-Client Override Hook

• Use filter asnet_themecore_editor_block_policy in theme to override:
• bypass_caps
• restricted_post_types
• allow_asnet_namespaces
• post_type_allowlists
• Practical approach: keep baseline list small, then extend per-client per post type.

Build and QA Commands

• npm install
• gulp tailwind
• gulp tailwind-critical
• gulp images
• gulp new-images
• gulp watch
• npm run release:theme

Script Requirements

• Node.js 20.x LTS and npm.
• PHP + Composer (needed for DevCore/OpenAI and plugin packaging workflows).
• ImageMagick CLI (magick) for image conversion tasks.
• Recommended command style across Linux/Windows:
• npx gulp ...
• npm run ...

Quick checks:

• node -v
• npm -v
• php -v
• composer -V
• magick -version

If magick is missing, Tailwind/JS tasks still work, but image conversion tasks (gulp images, gulp new-images) will fail.

ImageMagick Pipeline In This Theme

• Source images:
• packages/asnet-core-theme/assets/images/
• Generated outputs:
• packages/asnet-core-theme/assets/images-min/
• Task behavior:
• gulp images processes the full image set.
• gulp new-images processes newly added/missing outputs.
• Outputs are generated as optimized derivatives (including WebP/AVIF support in the pipeline).

Practical usage: 1. Add/replace source images in assets/images/. 2. Run npx gulp images (or npx gulp new-images during iterative work). 3. Reference generated assets from assets/images-min/ in templates/components. 4. Re-run image tasks after replacing source files.

Plugin Integration Expectations

• Baseline project stack: asnet-core-theme + asnet-devcore-plugin.
• MLS/client plugins are added as needed (iyba, yachtworld, yatco, cya, etc.).
• Seed-driven plugins require client config upload and plugin reactivation.
• DevCore exposes editable client/contact/social metadata in its Config tab and mirrors it to asnet_client_info.
• Theme work should continue even when a plugin is not present.

Seed + Rewrite Order Of Operations

• Activate plugin(s), upload seed files in plugin Seed tabs, then deactivate/reactivate plugin(s).
• Activate theme last so plugin-aware example pages and menus align to what is installed/configured.
• Until seed activation is complete, admin tabs remain limited by design (including IYBA Config) for uniform behavior across MLS plugins.
• Visit an admin page once so theme page-sync hooks run and plugin detail-page options are updated.
• Save permalinks once in Settings > Permalinks to force a full rewrite refresh.
• Verify plugin rewrite options and page IDs in your rewrite/debug tooling (devcore rewrite tab is sufficient).
• Validate canonical URLs from cards:
• IYBA: /listings/{slug}/{id}/
• YachtWorld: /listings/{slug}/{documentId}-{endpoint}/
• YATCO: /listings/{slug}/{id}-6/
• CYA: /listings/{slug}/{id}-7/

Example UI Consistency

• IYBA, YachtWorld, and YATCO examples are intentionally kept visually and structurally similar as wiring references.
• Card grids for search/inventory/favorites use the same responsive max density (up to 4 columns on wide screens).

Release Notes for Handoff

• npm run build inside a package only builds that package assets.
• Zip artifacts are created by root release scripts, not package-local build commands.
• Verify output files in dist/releases/ before deployment.