npm - @semi-solid/compiler - Versions diffs - 0.1.0 - Mend

@semi-solid/compiler 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,645 @@
+import { Plugin } from 'vite';
+export { BrandConfig, SemiSolidConfig } from './cli/config.js';
+/**
+ * plugin.ts
+ *
+ * Main Vite plugin entry point for Semi-Solid.
+ *
+ * During the build, this plugin intercepts .tsx/.jsx files and:
+ *   1. Extracts tap() mappings
+ *   2. Generates a .liquid file and writes it to the output directory
+ *   3. Returns the cleaned source code (tap() replaced by fallbacks)
+ *      for Vite/SolidJS to compile into the JS bundle
+ *
+ * Phase 1 handles: components in src/components/ → snippets/*.liquid
+ * Phase 3 will add: routes in src/routes/ → templates/*.liquid
+ */
+interface SemiSolidOptions {
+    /** Brand identifier, e.g. 'brand-a' */
+    brand: string;
+    /** Locale identifier, e.g. 'en' */
+    locale: string;
+    /**
+     * Output directory for the Shopify theme.
+     * Defaults to `dist/${brand}/${locale}`.
+     */
+    outDir?: string;
+    /**
+     * Phase 12: external server personalization.
+     * When configured, tapPersonalized() calls generate preconnect and prefetch
+     * tags so the fetch starts as soon as the HTML parser hits <head>.
+     */
+    personalization?: {
+        baseUrl: string;
+        preconnect?: boolean;
+        prefetch?: boolean;
+    };
+}
+declare function semiSolidPlugin(options: SemiSolidOptions): Plugin;
+/**
+ * tap-extract.ts
+ *
+ * Extracts tap() mappings from a component's source and produces a
+ * cleaned version of the source suitable for the client-side JS bundle
+ * (where tap() calls are replaced by their fallback values).
+ *
+ * Uses oxc-parser for fast AST parsing and magic-string for
+ * source-map-preserving replacements.
+ */
+interface TapMapping {
+    /** Variable name (or __tap_inline_N__ for inline calls) → Liquid expression */
+    [variableName: string]: string;
+}
+interface PersonalizedCallInfo {
+    /** LHS variable name */
+    varName: string;
+    /** API endpoint URL (first arg) */
+    url: string;
+    /** paramKey → tap variable name used as the param value */
+    params: Record<string, string>;
+}
+interface TapExtractResult {
+    /** Map of variable name → liquid expression string */
+    mappings: TapMapping;
+    /** Source with tap() calls replaced by fallbacks, for the JS bundle */
+    cleanedSource: string;
+    /** Source map for the cleaned source */
+    sourceMap: string;
+    /** Any warnings generated during extraction */
+    warnings: string[];
+    /**
+     * Variable names bound via tapWhen() — these need a data section so the
+     * runtime can re-fetch their values when the dep signals change.
+     */
+    reactiveVars: Set<string>;
+    /**
+     * PascalCase component names referenced via tapRemote() — the plugin
+     * generates a wrapper section for each so Shopify can render the snippet.
+     */
+    remoteComponents: Set<string>;
+    /**
+     * tapPersonalized() calls found in this component — each describes an
+     * external API endpoint, its param-to-tap-variable mapping, and the LHS
+     * variable name.
+     */
+    personalizedCalls: PersonalizedCallInfo[];
+}
+declare function extractTapMappings(source: string, filename?: string): TapExtractResult;
+/**
+ * css.ts
+ *
+ * Phase 7: CSS handling for Shopify theme builds.
+ *
+ * Resolves brand-specific and global CSS entry points, and generates
+ * the Liquid asset include tags needed in layout/theme.liquid.
+ *
+ * Shopify theme CSS lives in assets/ and is referenced via a direct <link> tag
+ * (not stylesheet_tag, which defers loading and causes FOUC):
+ *   <link rel="stylesheet" href="{{ 'theme.css' | asset_url }}" media="all">
+ *
+ * JS assets use the modern module pattern (script_tag is deprecated):
+ *   <script src="{{ 'theme.entry.js' | asset_url }}" type="module"></script>
+ */
+interface CSSFile {
+    /** Absolute path to the CSS source file. */
+    src: string;
+    /** Filename the file will have inside the Shopify theme's assets/ directory. */
+    assetName: string;
+}
+/**
+ * Resolves CSS files for a brand build.
+ *
+ * Looks for (in precedence order):
+ *   1. src/brands/{brand}/theme.css     → assets/theme.css  (brand-specific styles)
+ *   2. src/styles/global.css            → assets/global.css (shared global CSS)
+ *   3. src/index.css                    → assets/index.css  (Tailwind entry, if present)
+ *
+ * All files that exist are returned — multiple CSS files are allowed.
+ */
+declare function resolveCSSFiles(brand: string, projectRoot: string, existsSync?: (p: string) => boolean): CSSFile[];
+/**
+ * Generates a render-blocking CSS include for a Shopify theme asset.
+ *
+ * Uses a direct <link> tag instead of the `| stylesheet_tag` Liquid filter.
+ * Shopify's stylesheet_tag defers loading with media="print" + onload swap,
+ * which causes a flash of unstyled content (FOUC) and layout shift.
+ * A plain <link rel="stylesheet"> is render-blocking by default, ensuring
+ * styles are applied before the first paint.
+ *
+ * Output: <link rel="stylesheet" href="{{ 'theme.css' | asset_url }}" media="all">
+ */
+declare function generateStylesheetTag(assetName: string): string;
+/**
+ * Generates a modern Shopify Liquid script include for a JS asset.
+ * Uses type="module" for ES modules. The deprecated `script_tag` filter
+ * is avoided — Shopify's own guidance recommends explicit <script> tags.
+ *
+ * Output: <script src="{{ 'theme.entry.js' | asset_url }}" type="module"></script>
+ */
+declare function generateScriptTag(assetName: string): string;
+interface PersonalizationAssetOptions {
+    baseUrl: string;
+    preconnect: boolean;
+    prefetch: boolean;
+    calls: Array<{
+        url: string;
+        params: Record<string, string>;
+        componentMappings: TapMapping;
+    }>;
+}
+/**
+ * Generates a `<link rel="preconnect">` tag for an external API origin.
+ * Extracts the origin (scheme + host) from the full URL.
+ */
+declare function generatePreconnectTag(baseUrl: string): string;
+/**
+ * Generates an inline `<script>` that prefetches personalized data.
+ *
+ * For each call, builds a Liquid-powered URL with `| url_encode` on each
+ * param value, wraps in an IIFE that stores the fetch promise on
+ * `window.__p[url]`.
+ *
+ * Param keys are sorted alphabetically to match the runtime's `buildUrl()`.
+ */
+declare function generatePrefetchScript(calls: PersonalizationAssetOptions['calls'], baseUrl: string): string;
+/**
+ * Generates a block of Liquid asset includes (CSS stylesheets + JS modules)
+ * suitable for insertion in the <head> of layout/theme.liquid.
+ *
+ * Ordering: preconnect → CSS → JS → prefetch script.
+ * Backward compatible — omitting personalization produces the same output.
+ */
+declare function generateAssetIncludes(cssAssets: string[], jsAssets: string[], personalization?: PersonalizationAssetOptions): string;
+/**
+ * hash.ts
+ *
+ * Phase 7: Content hashing for asset cache busting.
+ *
+ * Shopify themes are served from a CDN with long-lived cache headers.
+ * Including a content hash in asset filenames ensures browsers and CDNs
+ * pick up changes immediately after a new theme is published.
+ *
+ * The 8-character hex hash format matches Vite's default for JS chunks,
+ * keeping all assets consistent.
+ */
+/**
+ * Computes a short content hash for cache busting.
+ *
+ * Returns the first 8 hex characters of the SHA-256 digest of the input.
+ * The same input always produces the same output (deterministic).
+ *
+ * hashContent('hello') → 'aaf4c61d'  (example)
+ */
+declare function hashContent(content: string): string;
+/**
+ * Produces a versioned asset filename by inserting the hash before the
+ * file extension — consistent with Vite's chunk naming convention.
+ *
+ * versionedName('theme.css', 'abc12345')       → 'theme-abc12345.css'
+ * versionedName('theme.entry.js', 'abc12345')  → 'theme.entry-abc12345.js'
+ * versionedName('logo', 'abc12345')            → 'logo-abc12345'
+ */
+declare function versionedName(basename: string, hash: string): string;
+/**
+ * Parses a versioned filename produced by `versionedName()` back into
+ * its original base name and hash.
+ *
+ * Returns null if the filename does not match the versioned format.
+ *
+ * parseVersionedName('theme-abc12345.css')      → { name: 'theme.css', hash: 'abc12345' }
+ * parseVersionedName('theme.entry-abc12345.js') → { name: 'theme.entry.js', hash: 'abc12345' }
+ * parseVersionedName('theme.css')               → null
+ */
+declare function parseVersionedName(filename: string): {
+    name: string;
+    hash: string;
+} | null;
+/**
+ * validation.ts
+ *
+ * Phase 7: Build validation and manifest generation.
+ *
+ * Provides utilities to catch common mistakes at build time:
+ *   - Using Liquid objects not available in the current route's context
+ *   - tap() variables extracted but never rendered into the Liquid output
+ *
+ * Also generates a build manifest (manifest.json) summarising all emitted files.
+ */
+/**
+ * Shopify Liquid objects that are available in every template context.
+ * These do not need to appear in each route's `context` array to be valid.
+ * See: https://shopify.dev/docs/api/liquid/objects
+ */
+declare const GLOBAL_LIQUID_OBJECTS: ReadonlySet<string>;
+type WarningType = 'context_mismatch' | 'unused_mapping';
+interface ValidationWarning {
+    type: WarningType;
+    /** Human-readable description of the issue. */
+    message: string;
+    /** The tap()-mapped variable name (component source identifier). */
+    variable: string;
+    /** The full Liquid expression string from the tap() call. */
+    liquidExpr: string;
+}
+interface BuildManifest {
+    brand: string;
+    locale: string;
+    /** Relative paths of Shopify template files written. */
+    templates: string[];
+    /** Relative paths of Shopify snippet files written. */
+    snippets: string[];
+    /** Relative paths of Shopify section files written. */
+    sections: string[];
+    /** Relative paths of JS/CSS asset files written. */
+    assets: string[];
+    /** Relative paths of locale JSON files copied. */
+    locales: string[];
+}
+/**
+ * Extracts the top-level Liquid object names referenced in a tap() mapping value.
+ *
+ * Examples:
+ *   '{{ product.title }}'                     → ['product']
+ *   '{{ product.price | money }}'             → ['product']
+ *   '{{ shop.name }}'                         → ['shop']
+ *   "{{ 'product.add_to_cart' | t }}"         → []  (string literal, no object)
+ *   'product'                                 → ['product'] (bare object ref)
+ *   '{{ cart.item_count }}'                   → ['cart']
+ */
+declare function extractLiquidObjects(liquidExpr: string): string[];
+/**
+ * Returns a warning for each tap() mapping that references a Liquid object
+ * not available in the given route context (and not in GLOBAL_LIQUID_OBJECTS).
+ *
+ * Example: using `{{ product.title }}` in an index route (which only has
+ * `shop` in its context) would produce a context_mismatch warning.
+ */
+declare function validateTapMappings(mappings: TapMapping, routeContext: string[]): ValidationWarning[];
+/**
+ * Returns a warning for each tap() mapping whose Liquid path does not appear
+ * anywhere in the generated Liquid output.
+ *
+ * A mapping is "unused in liquid" when the variable was extracted from tap()
+ * but its JSX usage was never compiled to a Liquid expression — for example,
+ * because it is used only inside a client-side event handler.
+ *
+ * Note: variables that appear in data-props (e.g. for hydration) ARE counted
+ * as "used" because their Liquid path appears in the data-props attribute.
+ *
+ * Skips synthetic inline tap() variable names (prefixed with __tap_inline_).
+ */
+declare function validateUnusedMappings(mappings: TapMapping, liquidOutput: string): ValidationWarning[];
+/**
+ * Generates a build manifest object summarising all files emitted during
+ * this build. Written to `manifest.json` in the theme output directory.
+ */
+declare function generateManifest(brand: string, locale: string, files: {
+    templates: string[];
+    snippets: string[];
+    sections?: string[];
+    assets: string[];
+    locales: string[];
+}): BuildManifest;
+/**
+ * hydration.ts
+ *
+ * Phase 6: Hydration Loader
+ *
+ * Provides utilities for detecting interactive SolidJS components and
+ * generating the hydration entry point for client-side island hydration.
+ */
+/**
+ * Returns true if the component source is interactive:
+ * - Uses createSignal or createEffect (SolidJS reactive primitives)
+ * - Has any on* JSX event handler attributes (onClick, onChange, etc.)
+ * - Uses tapWhen() (reactive tap — implies createTapSignal at runtime)
+ */
+declare function isInteractiveComponent(source: string): boolean;
+/**
+ * Finds tap-mapped variable names that are used inside event handler
+ * function bodies. These are the variables the JS bundle needs at
+ * runtime (e.g. the product handle to call Shopify's cart API).
+ *
+ * Walks on* JSX attribute values and the bodies of any named functions
+ * they reference, collecting identifier names that are keys in `mappings`.
+ */
+declare function detectPropVars(source: string, mappings: TapMapping): string[];
+/**
+ * Builds the data-props attribute value for a hydrated component.
+ *
+ * Each tap-mapped prop is serialized with the | json Liquid filter so
+ * the server-rendered value is available to the client JS bundle.
+ *
+ * Some Shopify objects (e.g. linklist links) don't support | json, so
+ * we detect those patterns and generate manual Liquid serialization.
+ *
+ * Example output for propVars = ['handle']:
+ *   { "handle": {{ product.handle | json }} }
+ */
+declare function generateDataProps(propVars: string[], mappings: TapMapping): string;
+/**
+ * Generates the content of `assets/theme.entry.js` — the Shopify theme
+ * entry script that mounts interactive components on the client.
+ *
+ * Uses SolidJS's render() (not hydrate()) because the DOM was produced by
+ * Shopify Liquid, not SolidJS's renderToString(). hydrate() requires
+ * SolidJS hydration markers that Liquid never emits; render() mounts fresh.
+ */
+declare function generateHydrationEntry(components: Array<{
+    name: string;
+    importPath: string;
+}>): string;
+/**
+ * liquid-gen.ts
+ *
+ * Generates a .liquid snippet from a SolidJS component's source code
+ * by walking the JSX AST and emitting Liquid equivalents.
+ *
+ * Phase 1: plain HTML, tap()-mapped variables in text/attributes, t() calls.
+ * Phase 2: <Show> → {% if %} / {% unless %}, <For> → {% for %}.
+ * Phase 3 (TODO): component imports → {% render 'snippet' %}.
+ */
+interface LiquidGenOptions {
+    /** Component name, e.g. 'ProductCard'. Used in error messages. */
+    componentName: string;
+    /** Indent string for pretty-printing. Default: two spaces. */
+    indent?: string;
+    /**
+     * Pre-computed data-props attribute value for client-side hydration.
+     * When set, the root HTML element receives data-component and data-props
+     * attributes so SolidJS's render() can target the SSR-rendered element.
+     * Generate this value with generateDataProps() from hydration.ts.
+     */
+    dataProps?: string;
+    /**
+     * Section ID for the companion JSON data section, e.g. 'product-card-data'.
+     * When set, the root HTML element also receives a data-section-id attribute
+     * so the hydration entry can pass it to createTapSignal() for tapWhen() calls.
+     */
+    dataSectionId?: string;
+    /**
+     * PascalCase names of components that are Shopify sections.
+     * When set, <ComponentName /> emits {% section 'component-name' %} instead
+     * of {% render 'component-name' %}.
+     */
+    sectionComponents?: Set<string>;
+    /**
+     * Mutable array that accumulates build-time warnings during Liquid generation.
+     * Callers can inspect this after generateLiquid() returns to surface warnings
+     * via the build tool (e.g. Vite/Rollup this.warn()).
+     */
+    warnings?: string[];
+}
+declare function generateLiquid(source: string, mappings: TapMapping, options: LiquidGenOptions): string;
+/**
+ * Lightweight helpers for navigating the oxc-parser AST.
+ *
+ * oxc-parser returns an ESTree-compatible AST but with some differences
+ * from Babel. The helpers here are intentionally defensive so they work
+ * across minor oxc version variations.
+ */
+interface AstNode {
+    type: string;
+    /** Byte offset of the node start in the source string (oxc-parser native) */
+    start?: number;
+    /** Byte offset of the node end in the source string (oxc-parser native) */
+    end?: number;
+    [key: string]: unknown;
+}
+/**
+ * Converts PascalCase or camelCase to kebab-case.
+ * e.g. ProductCard → product-card, CartDrawer → cart-drawer
+ */
+declare function toKebabCase(name: string): string;
+/**
+ * control-flow.ts
+ *
+ * Utilities for resolving SolidJS control-flow components (<Show>, <For>)
+ * to their Liquid equivalents.
+ *
+ * These functions operate on oxc-parser AST nodes and are consumed by
+ * liquid-gen.ts during JSX → Liquid compilation.
+ */
+interface ShowCondition {
+    /** The bare Liquid expression, e.g. 'product.available' or 'item.in_stock' */
+    liquidExpr: string;
+    /**
+     * When true, use {% unless %} / {% endunless %}.
+     * Produced by <Show when={!condition}>.
+     */
+    negated: boolean;
+}
+interface ForIteration {
+    /** The Liquid collection expression, e.g. 'product.images' */
+    collection: string;
+    /** The loop variable name taken from the JSX render function param */
+    loopVar: string;
+}
+/**
+ * Resolves the `when` expression from `<Show when={expr}>` to a Liquid condition.
+ *
+ * Returns null when the condition is purely client-side (e.g. a signal call,
+ * a complex expression, or an identifier that is not tap()-mapped).
+ *
+ * Supported patterns:
+ *   when={tapMapped}        → { liquidExpr: 'product.available', negated: false }
+ *   when={!tapMapped}       → { liquidExpr: 'product.available', negated: true }
+ *   when={loopVar}          → { liquidExpr: 'item', negated: false }
+ *   when={loopVar.prop}     → { liquidExpr: 'item.in_stock', negated: false }
+ *   when={!loopVar.prop}    → { liquidExpr: 'item.in_stock', negated: true }
+ */
+declare function resolveShowCondition(whenExpr: AstNode, mappings: TapMapping, loopVars: Set<string>, warnings?: string[]): ShowCondition | null;
+/**
+ * Resolves the `each` expression from `<For each={expr}>` to a ForIteration.
+ *
+ * Returns null if the collection is not tap()-mapped (i.e. it's a purely
+ * client-side array).
+ *
+ * @param eachExpr    The AST node for the `each` attribute value
+ * @param loopVarName The render-function parameter name (the loop variable)
+ * @param mappings    tap() mappings from the component
+ */
+declare function resolveForIteration(eachExpr: AstNode, loopVarName: string, mappings: TapMapping, loopVars?: Set<string>, warnings?: string[]): ForIteration | null;
+/**
+ * Walks a (possibly nested) MemberExpression and builds a dot-separated
+ * Liquid path when the root identifier is a loop variable or tap()-mapped object.
+ *
+ * Examples:
+ *   image              (loop var)           → 'image'
+ *   image.url          (loop var + prop)    → 'image.url'
+ *   image.assets.src   (deeper)             → 'image.assets.src'
+ *   product            (tap mapped 'product') → 'product'
+ *
+ * Returns null for:
+ *   - Computed accesses (arr[0], obj[key])
+ *   - Root identifiers that are neither loop vars nor tap-mapped
+ */
+declare function resolveMemberPath(node: AstNode, mappings: TapMapping, loopVars: Set<string>): string | null;
+/**
+ * Strips `{{ }}` braces from a Liquid expression string so it can be used
+ * in tag context ({% if expr %}, {% for x in expr %}).
+ *
+ * '{{ product.available }}'  → 'product.available'
+ * 'product.images'           → 'product.images'   (already plain)
+ * '{% raw tag %}'            → returned unchanged
+ */
+declare function stripLiquidBraces(liquidStr: string): string;
+/**
+ * route-map.ts
+ *
+ * Maps src/routes/+layout.tsx to Shopify layout/theme.liquid.
+ *
+ * Page templates are now JSON files in templates/ (copied directly to dist).
+ * Only the layout file needs the tap-extract → liquid-gen pipeline.
+ */
+interface RouteInfo {
+    /** Shopify template identifier, e.g. '_layout' */
+    template: string;
+    /** Relative output path from the theme root, e.g. 'layout/theme.liquid' */
+    outputPath: string;
+    /** Liquid context objects available in this template */
+    context: string[];
+    /** Whether this is the layout file (+layout.tsx → layout/theme.liquid) */
+    isLayout: boolean;
+}
+/**
+ * Given a route file's absolute path and the routes directory, returns
+ * the RouteInfo describing the Shopify output for that file.
+ *
+ * Only +layout files are recognized. All other route files return null
+ * since page templates are now JSON files in templates/.
+ */
+declare function resolveRoute(filePath: string, routesDir: string): RouteInfo | null;
+/**
+ * Returns true if the file is inside src/routes/.
+ */
+declare function isRouteFile(filePath: string, projectRoot: string): boolean;
+/**
+ * Returns the absolute path to the routes directory for a project root.
+ */
+declare function getRoutesDir(projectRoot: string): string;
+/**
+ * brand-resolve.ts
+ *
+ * Vite plugin that resolves `$snippets/`, `$sections/`, and `$blocks/` imports
+ * to either:
+ *   1. src/brands/{brand}/{category}/ComponentName.tsx  — brand-specific override
+ *   2. src/{category}/ComponentName.tsx                 — base component fallback
+ *
+ * Resolution stops at the first match. If neither exists, the plugin returns
+ * null and Vite continues with its normal alias/module resolution.
+ *
+ * Usage in vite.config.ts (must come BEFORE solidPlugin):
+ *   plugins: [createBrandResolver('brand-a'), solidPlugin(), semiSolidPlugin(...)]
+ *
+ * Component imports opt into brand resolution by using category prefixes:
+ *   import ProductCard from '$snippets/ProductCard';     // ← brand-resolved
+ *   import ProductSection from '$sections/ProductSection'; // ← brand-resolved
+ *   import ImageGallery from '$blocks/ImageGallery';     // ← brand-resolved
+ *   import Something from '../relative/path';            // ← not resolved here
+ */
+/**
+ * Resolves a component name by searching across all categories.
+ *
+ * Used by the plugin's buildStart to locate components without knowing
+ * which category they belong to.
+ *
+ * @param componentPath - The component name, e.g. 'ProductCard'
+ * @param brand         - Brand identifier, e.g. 'brand-a'
+ * @param projectRoot   - Absolute project root path
+ * @param existsSync    - File existence check (defaults to fs.existsSync)
+ */
+declare function resolveBrandPath(componentPath: string, brand: string, projectRoot: string, existsSync?: (p: string) => boolean): string | null;
+/**
+ * Creates a Vite plugin that performs brand-aware component resolution for
+ * all `$snippets/*`, `$sections/*`, and `$blocks/*` imports.
+ *
+ * @param brand       - Brand identifier, e.g. 'brand-a'
+ * @param projectRoot - Optional: explicit project root (mainly for testing)
+ */
+declare function createBrandResolver(brand: string, projectRoot?: string): Plugin;
+/**
+ * i18n.ts
+ *
+ * Utilities for locale file resolution during the build step.
+ *
+ * Shopify theme locales directory conventions:
+ *   locales/
+ *     en.default.json   ← the locale this theme build is primary for
+ *     fr.json           ← additional locales understood by the storefront
+ *     de.json
+ *
+ * Source locale files live at:
+ *   src/brands/{brand}/i18n/{locale}.json
+ *
+ * The `resolveLocaleFiles` function returns the {src, dest} pairs so
+ * that the plugin can copy them without knowing filesystem details
+ * itself — the pure function form also makes unit-testing trivial.
+ *
+ * The `VIRTUAL_LOCALE_MODULE` id is provided to the Vite plugin so
+ * JS bundles can import the locale data at build time:
+ *
+ *   import translations from 'virtual:semi-solid/locale';
+ *   setTranslations(translations);
+ */
+/** Vite virtual module id for the active locale JSON. */
+declare const VIRTUAL_LOCALE_MODULE = "virtual:semi-solid/locale";
+interface LocaleFilePair {
+    /** Absolute path to the source JSON in src/brands/{brand}/i18n/ */
+    src: string;
+    /** Absolute path to the destination inside the Shopify locales/ dir */
+    dest: string;
+}
+/**
+ * Determines all locale file copy pairs for a brand+locale build.
+ *
+ * The active `locale` is written as `{locale}.default.json` in the
+ * output; all other JSON files in the i18n directory keep their name
+ * (e.g. `fr.json` stays `fr.json`).
+ *
+ * Returns an empty array if the i18n source directory doesn't exist.
+ *
+ * @param brand       - Brand identifier, e.g. 'brand-a'
+ * @param locale      - Active build locale, e.g. 'en'
+ * @param projectRoot - Absolute path to the project root
+ * @param outDir      - Absolute path to the Shopify theme output directory
+ * @param existsSync  - Directory existence check (injectable for testing)
+ * @param readdirSync - Directory listing returning filenames (injectable)
+ */
+declare function resolveLocaleFiles(brand: string, locale: string, projectRoot: string, outDir: string, existsSync?: (p: string) => boolean, readdirSync?: (dir: string) => string[]): LocaleFilePair[];
+/**
+ * Returns the absolute path to the active locale JSON file for a build,
+ * or null if it doesn't exist.
+ *
+ * Used by the plugin's virtual module to inline translations into the bundle.
+ */
+declare function resolveActiveLocalePath(brand: string, locale: string, projectRoot: string, existsSync?: (p: string) => boolean): string | null;
+/**
+ * Returns the two virtual-module ids for use in a Vite plugin's
+ * `resolveId` and `load` hooks.
+ */
+declare const virtualLocaleIds: {
+    readonly external: "virtual:semi-solid/locale";
+    readonly internal: string;
+};
+export { type BuildManifest, type CSSFile, type ForIteration, GLOBAL_LIQUID_OBJECTS, type LiquidGenOptions, type LocaleFilePair, type PersonalizationAssetOptions, type PersonalizedCallInfo, type RouteInfo, type SemiSolidOptions, type ShowCondition, type TapExtractResult, type TapMapping, VIRTUAL_LOCALE_MODULE, type ValidationWarning, type WarningType, createBrandResolver, detectPropVars, extractLiquidObjects, extractTapMappings, generateAssetIncludes, generateDataProps, generateHydrationEntry, generateLiquid, generateManifest, generatePreconnectTag, generatePrefetchScript, generateScriptTag, generateStylesheetTag, getRoutesDir, hashContent, isInteractiveComponent, isRouteFile, parseVersionedName, resolveActiveLocalePath, resolveBrandPath, resolveCSSFiles, resolveForIteration, resolveLocaleFiles, resolveMemberPath, resolveRoute, resolveShowCondition, semiSolidPlugin, stripLiquidBraces, toKebabCase, validateTapMappings, validateUnusedMappings, versionedName, virtualLocaleIds };