@stacksjs/stx 0.2.342 → 0.2.343

package/dist/directive-arguments.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Argument handling for directives whose arguments are expressions.
+ *
+ * Written for the SEO directives (`@seo`, `@meta`, `@metaTag`,
+ * `@structuredData`), and kept free of anything SEO-specific so a custom
+ * directive can use it too (`CustomDirective.rawParams`).
+ *
+ * Every one of these used to fail the same way: an argument that was not the
+ * one shape its regex expected was either left in the page as literal text or
+ * replaced with nothing, and no one was told. `@seo(seo)` never matched a
+ * pattern that insisted on `{`; `@meta('author', post.author)` sent the words
+ * "post.author" as the author; `@structuredData(prodcut)` emitted a JSON-LD
+ * block holding nothing but `@context`. Each page looked fine and was wrong
+ * where it counts, in a link preview or a search result.
+ *
+ * So the directives share one way to find their call (balanced and quote-aware,
+ * so `'Smile :)'` does not end the call early), one way to tell a string literal
+ * from an expression, one evaluator that can say WHY a value is missing, and one
+ * way to report a failure: an inline comment where the tag would have been, plus
+ * a console warning naming the file.
+ */
+import type { ErrorCode } from './errors/codes';
+export interface DirectiveCall {
+    /** Index of the `@`. */
+    start: number;
+    /** Index one past the closing paren, or -1 when the call is never closed. */
+    end: number;
+    /** The text between the parens, as written. */
+    args: string;
+    /** The whole call, `@name(...)`, or its first 80 characters when unclosed. */
+    call: string;
+}
+/**
+ * Every `@name(...)` call in `template` matched by `pattern`, in order.
+ *
+ * `pattern` must be global and end at the opening paren. The closing paren is
+ * found by balance, skipping parens inside strings, so an argument may hold any
+ * expression: `@seo(build({ title: 'Smile :)' }))` is one call.
+ */
+export declare function findDirectiveCalls(template: string, pattern: RegExp): DirectiveCall[];
+/**
+ * Replace every call {@link findDirectiveCalls} finds.
+ *
+ * One left-to-right pass over the original text: a replacement is never
+ * rescanned, so markup that happens to contain the directive's name cannot
+ * loop. A call with no closing paren keeps its text, preceded by whatever
+ * `onUnterminated` returns, so the author sees both the report and the call.
+ */
+export declare function replaceDirectiveCalls(template: string, pattern: RegExp, replace: (args: string, call: string) => string, onUnterminated: (call: string) => string): string;
+/**
+ * Split an argument list at its top-level commas.
+ *
+ * Commas inside strings, template literals, brackets, braces and parens belong
+ * to the argument they sit in: `'a, b', fn(x, y)` is two arguments, not four.
+ * Arguments come back trimmed and exactly as written, quotes included, so the
+ * caller can still tell `'title'` (the word) from `title` (a variable).
+ */
+export declare function splitTopLevelArgs(args: string): string[];
+/**
+ * The value of `raw` when it is exactly one string literal, otherwise `null`.
+ *
+ * `'a' + b`, `'a' || 'b'` and a template literal with `${}` in it are
+ * expressions and return `null`. A literal is read here rather than handed to
+ * the evaluator because the evaluator's safety screen reads words, and a
+ * description is allowed to say "eval".
+ */
+export declare function parseStringLiteral(raw: string): string | null;
+export type EvaluatedArgument = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    message: string;
+    code: ErrorCode;
+};
+/**
+ * Evaluate a directive argument against the template's context.
+ *
+ * The shared evaluator turns every failure into `undefined`, which is right for
+ * `{{ }}` and wrong here: a directive whose whole job is to produce a tag has
+ * to be able to say why it produced none. So the three ways an expression
+ * fails are told apart:
+ *
+ * - it is not allowed (the safety screen) or not JavaScript (a syntax error);
+ * - it names a variable the template does not have, which is almost always a
+ *   value declared in a plain (client) `<script>`, or a typo;
+ * - it is an object or array literal that came back `undefined`, which only
+ *   happens when something inside it threw.
+ *
+ * A defined variable that simply holds `null` or `undefined` is not a failure:
+ * `@seo(page.seo)` on a page without one is allowed to render nothing.
+ */
+export declare function evaluateDirectiveArgument(expression: string, context: Record<string, unknown>): EvaluatedArgument;
+/** How a value reads in an error message. */
+export declare function describeValue(value: unknown): string;
+/** A plain object: not null, not an array. */
+export declare function isPlainRecord(value: unknown): value is Record<string, unknown>;
+/** The call as it reads in a message: one line, and not the whole object. */
+export declare function shortCall(call: string): string;
+/**
+ * Report a directive that produced nothing: a console warning naming the file,
+ * and an inline comment where the tag would have been, for whoever reads the
+ * built HTML (which is how most of these were found).
+ */
+export declare function reportDirectiveFailure(label: string, call: string, message: string, filePath: string, code?: ErrorCode): string;
+/** Warn without replacing anything: the directive rendered, but not all of it. */
+export declare function warnDirective(call: string, message: string, filePath: string): void;

package/dist/directive-arguments.js

@@ -0,0 +1,171 @@
+import path from "node:path";
+import { ErrorCodes, inlineError } from "./error-handling.js";
+import { findMatchingDelimiter } from "./parser/tokenizer.js";
+import { createSafeContext, createSafeFunction, freeIdentifiers, getExpressionSafetyRule } from "./safe-evaluator.js";
+export function findDirectiveCalls(template, pattern) {
+  const calls = [];
+  pattern.lastIndex = 0;
+  let match;
+  while ((match = pattern.exec(template)) !== null) {
+    const start = match.index, openParen = start + match[0].length - 1, closeParen = findMatchingDelimiter(template, "(", ")", openParen);
+    if (closeParen === -1) {
+      calls.push({ start, end: -1, args: "", call: template.slice(start, Math.min(template.length, start + 80)) });
+      pattern.lastIndex = openParen + 1;
+      continue;
+    }
+    calls.push({
+      start,
+      end: closeParen + 1,
+      args: template.slice(openParen + 1, closeParen),
+      call: template.slice(start, closeParen + 1)
+    });
+    pattern.lastIndex = closeParen + 1;
+  }
+  return calls;
+}
+export function replaceDirectiveCalls(template, pattern, replace, onUnterminated) {
+  let output = "", cursor = 0;
+  for (const found of findDirectiveCalls(template, pattern)) {
+    output += template.slice(cursor, found.start);
+    if (found.end === -1) {
+      output += onUnterminated(found.call);
+      cursor = found.start;
+      continue;
+    }
+    output += replace(found.args, found.call);
+    cursor = found.end;
+  }
+  return output + template.slice(cursor);
+}
+export function splitTopLevelArgs(args) {
+  const parts = [];
+  let depth = 0, quote = null, current = "";
+  for (let i = 0;i < args.length; i++) {
+    const char = args[i];
+    if (quote) {
+      current += char;
+      if (char === "\\" && i + 1 < args.length) {
+        current += args[++i];
+        continue;
+      }
+      if (char === quote)
+        quote = null;
+      continue;
+    }
+    if (char === "'" || char === '"' || char === "`")
+      quote = char;
+    else if (char === "(" || char === "[" || char === "{")
+      depth++;
+    else if (char === ")" || char === "]" || char === "}")
+      depth--;
+    else if (char === "," && depth === 0) {
+      parts.push(current.trim());
+      current = "";
+      continue;
+    }
+    current += char;
+  }
+  if (current.trim())
+    parts.push(current.trim());
+  return parts;
+}
+export function parseStringLiteral(raw) {
+  const text = raw.trim(), quote = text[0];
+  if (quote !== "'" && quote !== '"' && quote !== "`" || text.length < 2 || text.at(-1) !== quote)
+    return null;
+  let value = "";
+  for (let i = 1;i < text.length - 1; i++) {
+    const char = text[i];
+    if (char === "\\" && i + 1 < text.length - 1) {
+      const next = text[++i];
+      value += next === "n" ? `
+` : next === "t" ? "\t" : next;
+      continue;
+    }
+    if (char === quote)
+      return null;
+    if (quote === "`" && char === "$" && text[i + 1] === "{")
+      return null;
+    value += char;
+  }
+  return value;
+}
+const NOT_VARIABLES = new Set([
+  "true",
+  "false",
+  "null",
+  "undefined",
+  "typeof",
+  "void",
+  "new",
+  "in",
+  "of",
+  "instanceof",
+  "this",
+  "delete",
+  "await",
+  "async",
+  "function",
+  "return",
+  "NaN",
+  "Infinity"
+]);
+export function evaluateDirectiveArgument(expression, context) {
+  const source = expression.trim();
+  if (!source)
+    return { ok: !1, message: "the argument is empty", code: ErrorCodes.INVALID_DIRECTIVE_SYNTAX };
+  const rule = getExpressionSafetyRule(source);
+  if (rule)
+    return { ok: !1, message: `the expression is not allowed (${rule})`, code: ErrorCodes.UNSAFE_EXPRESSION };
+  const safeContext = createSafeContext(context);
+  let value;
+  try {
+    value = createSafeFunction(source, Object.keys(safeContext))(...Object.values(safeContext));
+  } catch (error) {
+    return { ok: !1, message: `the expression could not be evaluated: ${error instanceof Error ? error.message : String(error)}`, code: ErrorCodes.EVALUATION_ERROR };
+  }
+  if (value !== void 0 && value !== null)
+    return { ok: !0, value };
+  const missing = [...new Set(freeIdentifiers(source))].filter((name) => !NOT_VARIABLES.has(name) && !(name in safeContext) && !(name in globalThis));
+  if (missing.length > 0)
+    return {
+      ok: !1,
+      message: `${missing.map((name) => `"${name}"`).join(", ")} ${missing.length === 1 ? "is" : "are"} not defined here. Values a directive reads must come from <script server> or the render context; a plain <script> runs in the browser. To pass literal text, quote it.`,
+      code: ErrorCodes.UNDEFINED_VARIABLE
+    };
+  if (value === void 0 && (source.startsWith("{") || source.startsWith("[")))
+    return { ok: !1, message: "the expression threw while it was evaluated", code: ErrorCodes.EVALUATION_ERROR };
+  return { ok: !0, value };
+}
+export function describeValue(value) {
+  if (value === null)
+    return "null";
+  if (Array.isArray(value))
+    return "an array";
+  if (typeof value === "object")
+    return "an object";
+  if (typeof value === "string")
+    return `a string ("${value.length > 40 ? `${value.slice(0, 40)}...` : value}")`;
+  return `${/^[aeiou]/.test(typeof value) ? "an" : "a"} ${typeof value}`;
+}
+export function isPlainRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function displayPath(filePath) {
+  if (!filePath)
+    return "";
+  return path.isAbsolute(filePath) ? path.relative(process.cwd(), filePath) || filePath : filePath;
+}
+export function shortCall(call) {
+  const flat = call.replace(/\s+/g, " ").trim();
+  return flat.length > 80 ? `${flat.slice(0, 77)}...` : flat;
+}
+export function reportDirectiveFailure(label, call, message, filePath, code = ErrorCodes.EVALUATION_ERROR) {
+  const where = filePath ? ` in ${displayPath(filePath)}` : "";
+  console.warn(`[stx] ${shortCall(call)}${where}: ${message}`);
+  return inlineError(label, `${shortCall(call)}: ${message}`, code);
+}
+export function warnDirective(call, message, filePath) {
+  const where = filePath ? ` in ${displayPath(filePath)}` : "";
+  console.warn(`[stx] ${shortCall(call)}${where}: ${message}`);
+}

package/dist/head.d.ts

@@ -1,32 +1,3 @@
-/**
- * STX Head Management
- *
- * Manage document head (title, meta, links, scripts) with a simple API.
- *
- * @example
- * ```typescript
- * import { useHead, useSeoMeta, definePageMeta } from 'stx'
- *
- * // Full control
- * useHead({
- *   title: 'My Page',
- *   meta: [{ name: 'description', content: '...' }]
- * })
- *
- * // SEO shorthand
- * useSeoMeta({
- *   title: 'My Page',
- *   description: 'Page description',
- *   ogImage: '/og.png'
- * })
- *
- * // Page configuration
- * definePageMeta({
- *   title: 'My Page',
- *   layout: 'default'
- * })
- * ```
- */
 export interface MetaTag {
     name?: string;
     property?: string;
@@ -284,11 +255,17 @@ export declare function processTitleDirective(content: string, context: Record<s
 /**
  * Process @meta directive.
  *
+ * Stages each tag on the render's head. Reached only when the render has no
+ * custom directives, since the registered `metaDirective` (seo.ts) takes every
+ * `@meta` first; both resolve their arguments with `resolveMetaArguments`, so
+ * a quoted value is text and anything else is an expression.
+ *
  * @example
  * ```html
  * @meta('description', 'Page description')
  * @meta('og:image', ogImageUrl)
+ * @meta('author', post.author)
  * ```
  */
-export declare function processMetaDirective(content: string, context: Record<string, unknown>): string;
+export declare function processMetaDirective(content: string, context: Record<string, unknown>, filePath?: string): string;
 export { usePageTitle as useTitle };

package/dist/head.js

@@ -1,3 +1,6 @@
+import { replaceDirectiveCalls, reportDirectiveFailure, splitTopLevelArgs } from "./directive-arguments.js";
+import { ErrorCodes } from "./error-handling.js";
+import { resolveMetaArguments } from "./meta-arguments.js";
 let currentHead = {};
 const headStack = [];
 let currentPageMeta = {};
@@ -237,12 +240,19 @@ export function processTitleDirective(content, context) {
     return "";
   });
 }
-export function processMetaDirective(content, context) {
-  return content.replace(/@meta\s*\(\s*(['"`])(.+?)\1\s*,\s*(?:(['"`])(.+?)\3|([^)]+))\s*\)/g, (_, _q1, name, q2, quotedValue, unquotedValue) => {
-    const value = q2 ? quotedValue : unquotedValue, resolvedValue = q2 ? value : context[(value || "").trim()] ?? value, meta = name.includes(":") ? { property: name, content: resolvedValue } : { name, content: resolvedValue }, existing = context.__stx_runtime_head ?? {};
-    context.__stx_runtime_head = mergeHeadConfigs(existing, { meta: [meta] });
+export function processMetaDirective(content, context, filePath = "") {
+  if (!content.includes("@meta"))
+    return content;
+  return replaceDirectiveCalls(content, /(?<![\w$@])@meta\s*\(/g, (args, call) => {
+    const resolved = resolveMetaArguments(splitTopLevelArgs(args), context);
+    if (resolved.kind === "error")
+      return reportDirectiveFailure("Meta", call, resolved.message, filePath, resolved.code);
+    if (resolved.kind === "tag") {
+      const existing = context.__stx_runtime_head ?? {};
+      context.__stx_runtime_head = mergeHeadConfigs(existing, { meta: [resolved.tag] });
+    }
     return "";
-  });
+  }, (call) => reportDirectiveFailure("Meta", call, "the call has no closing parenthesis", filePath, ErrorCodes.INVALID_DIRECTIVE_SYNTAX));
 }
 
 export {

package/dist/meta-arguments.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Resolving `@meta(...)` arguments to a tag.
+ *
+ * `@meta` has three entry points -- the registered custom directive that stages
+ * the tag on the head (seo.ts `metaDirective`), the head pass for renders
+ * without custom directives (head.ts `processMetaDirective`), and the inline
+ * pass that partials use (seo.ts `processMetaDirectives`) -- and they used to
+ * read their arguments three different ways. A quoted value could be looked up
+ * in the context as if it were a variable name, and an unquoted one that was
+ * not a bare variable (`post.author`) was sent as literal text. One resolver
+ * now serves all three. It lives apart from both seo.ts and head.ts because
+ * seo.ts already imports head.ts.
+ */
+import type { ErrorCode } from './errors/codes';
+/**
+ * Namespaces whose tags are addressed by `property`, not `name`.
+ *
+ * Open Graph and its relatives are RDFa vocabularies, so the attribute is
+ * `property`; a `<meta name="og:title">` is ignored by every scraper that
+ * implements the spec. Twitter cards are the exception people expect to be a
+ * property and are not: the card spec says `name`.
+ */
+export declare const PROPERTY_NAMESPACES: string[];
+export type MetaTagAttrs = {
+    name: string;
+    content: string;
+} | {
+    property: string;
+    content: string;
+};
+export type ResolvedMeta = {
+    kind: 'tag';
+    tag: MetaTagAttrs;
+} | {
+    kind: 'empty';
+} | {
+    kind: 'error';
+    message: string;
+    code: ErrorCode;
+};
+/**
+ * Resolve `@meta(...)` arguments, given as written (quotes kept), to a tag.
+ *
+ * - `@meta('author', 'Jane')`: literal text. A quoted value is never looked up
+ *   in the context, so `@meta('description', 'title')` means the word.
+ * - `@meta('author', author)`, `@meta('og:title', post.title)`,
+ *   `@meta('keywords', tags)`: the second argument is evaluated. An array joins
+ *   with ", "; `null`, `undefined`, `false` and `''` render nothing.
+ * - `@meta('og:title')`: the one-argument form reads the context by the part
+ *   after the colon (`title`), then `openGraph.title`.
+ */
+export declare function resolveMetaArguments(args: string[], context: Record<string, unknown>): ResolvedMeta;

package/dist/meta-arguments.js

@@ -0,0 +1,55 @@
+import { ErrorCodes } from "./error-handling.js";
+import { describeValue, evaluateDirectiveArgument, isPlainRecord, parseStringLiteral } from "./directive-arguments.js";
+export const PROPERTY_NAMESPACES = ["og:", "article:", "book:", "profile:", "fb:", "music:", "video:"];
+const BARE_META_NAME = /^[a-z][\w-]*(?::[\w:-]+)?$/i;
+export function resolveMetaArguments(args, context) {
+  if (args.length < 1)
+    return { kind: "error", message: "meta directive requires at least the meta name", code: ErrorCodes.INVALID_DIRECTIVE_SYNTAX };
+  if (args.length > 2)
+    return { kind: "error", message: `@meta takes a name and a value, got ${args.length} arguments`, code: ErrorCodes.INVALID_DIRECTIVE_SYNTAX };
+  const name = resolveMetaName(args[0], context);
+  if (typeof name !== "string")
+    return name;
+  let content;
+  if (args.length === 2) {
+    const value = resolveMetaValue(args[1], context);
+    if (typeof value !== "string")
+      return value;
+    content = value;
+  } else {
+    const segment = name.includes(":") ? name.slice(name.indexOf(":") + 1) : name, openGraph = context.openGraph, found = context[segment] ?? (isPlainRecord(openGraph) ? openGraph[segment] : void 0);
+    content = found === void 0 || found === null || typeof found === "object" ? "" : String(found);
+  }
+  if (!content)
+    return { kind: "empty" };
+  return { kind: "tag", tag: PROPERTY_NAMESPACES.some((prefix) => name.startsWith(prefix)) ? { property: name, content } : { name, content } };
+}
+function resolveMetaName(raw, context) {
+  const literal = parseStringLiteral(raw);
+  if (literal !== null)
+    return literal.trim() ? literal : { kind: "error", message: "the meta name is empty", code: ErrorCodes.INVALID_DIRECTIVE_SYNTAX };
+  if (BARE_META_NAME.test(raw.trim()))
+    return raw.trim();
+  const result = evaluateDirectiveArgument(raw, context);
+  if (!result.ok)
+    return { kind: "error", message: `meta name: ${result.message}`, code: result.code };
+  if (typeof result.value !== "string" || !result.value.trim())
+    return { kind: "error", message: `the meta name must be a non-empty string, got ${describeValue(result.value)}`, code: ErrorCodes.TYPE_ERROR };
+  return result.value;
+}
+function resolveMetaValue(raw, context) {
+  const literal = parseStringLiteral(raw);
+  if (literal !== null)
+    return literal;
+  const result = evaluateDirectiveArgument(raw, context);
+  if (!result.ok)
+    return { kind: "error", message: result.message, code: result.code };
+  const value = result.value;
+  if (value === void 0 || value === null || value === !1)
+    return "";
+  if (Array.isArray(value))
+    return value.filter((item) => item !== void 0 && item !== null && item !== "").map(String).join(", ");
+  if (typeof value === "object" && !(value instanceof Date))
+    return { kind: "error", message: `the content must be text, got ${describeValue(value)}`, code: ErrorCodes.TYPE_ERROR };
+  return String(value);
+}

package/dist/process.js

@@ -725,7 +725,7 @@ async function processOtherDirectives(template, context, filePath, options, depe
     context.__stx_head_raw = `${context.__stx_head_raw || ""}${headResult.headContent}
 `;
   output = processTitleDirective(output, context);
-  output = processMetaDirective(output, context);
+  output = processMetaDirective(output, context, filePath);
   output = processRouteDirectives(output);
   output = processAuthDirectives(output, context);
   output = processCsrfDirectives(output);

package/dist/pwa.js

@@ -1,6 +1,6 @@
 // @bun
-import{Fk as wq,Gk as dq,Hk as Cq,Ik as mq,Jk as gq}from"./chunk-wvc7t11n.js";import{Kk as S,Lk as Tq,Mk as _q,Nk as z,Ok as D,Pk as P,Qk as kq,Rk as vq,Sk as w,Tk as Iq,Uk as d,Vk as Hq,Wk as Oq,Xk as Mq}from"./chunk-yzv702kk.js";import{ow as Aq,pw as bq,qw as Sq,rw as zq,sw as Dq,tw as Pq}from"./chunk-yr7camcd.js";import{xw as N}from"./chunk-p5d8sb50.js";import p from"fs";import E from"path";import C from"fs";import L from"path";var k=[72,96,128,144,152,192,384,512],v=[120,152,167,180],I=[16,32];async function H(G,B){let q={success:!0,generatedFiles:[],errors:[],warnings:[]},K=G.pwa?.icons;if(!K?.src)return q.errors.push("No source icon specified in pwa.icons.src"),q.success=!1,q;let Y=L.isAbsolute(K.src)?K.src:L.resolve(process.cwd(),K.src);if(!await Bun.file(Y).exists())return q.errors.push(`Source icon not found: ${Y}`),q.success=!1,q;let Q=L.resolve(B,K.outputDir||"pwa-icons");try{C.mkdirSync(Q,{recursive:!0})}catch{return q.errors.push(`Failed to create output directory: ${Q}`),q.success=!1,q}let X=K.sizes||k,j=K.generateWebP??!0,J=K.generateAppleIcons??!0;try{let y;try{y=await import("sharp")}catch{return q.errors.push(`sharp is not installed. Install it with: bun add sharp
-Icon generation requires the sharp package for image processing.`),q.success=!1,q}let R=await y.default(Y).metadata();if(R.width&&R.width<512)q.warnings.push(`Source icon is ${R.width}x${R.height}. Recommend using at least 512x512 for best quality.`);for(let $ of X){let x=L.join(Q,`icon-${$}x${$}.png`);if(await y.default(Y).resize($,$,{fit:"contain",background:{r:0,g:0,b:0,alpha:0}}).png().toFile(x),q.generatedFiles.push(x),j){let F=L.join(Q,`icon-${$}x${$}.webp`);await y.default(Y).resize($,$,{fit:"contain",background:{r:0,g:0,b:0,alpha:0}}).webp({quality:90}).toFile(F),q.generatedFiles.push(F)}}if(J){for(let x of v){let F=L.join(Q,`apple-touch-icon-${x}x${x}.png`);await y.default(Y).resize(x,x,{fit:"contain",background:{r:255,g:255,b:255,alpha:1}}).png().toFile(F),q.generatedFiles.push(F)}let $=L.join(Q,"apple-touch-icon.png");await y.default(Y).resize(180,180,{fit:"contain",background:{r:255,g:255,b:255,alpha:1}}).png().toFile($),q.generatedFiles.push($)}for(let $ of I){let x=L.join(Q,`favicon-${$}x${$}.png`);await y.default(Y).resize($,$,{fit:"contain",background:{r:0,g:0,b:0,alpha:0}}).png().toFile(x),q.generatedFiles.push(x)}let U=512,T=L.join(Q,`icon-maskable-${U}x${U}.png`),Z=Math.floor(U*0.1),_=U-Z*2;await y.default(Y).resize(_,_,{fit:"contain",background:{r:0,g:0,b:0,alpha:0}}).extend({top:Z,bottom:Z,left:Z,right:Z,background:{r:255,g:255,b:255,alpha:1}}).png().toFile(T),q.generatedFiles.push(T)}catch(y){let V=y instanceof Error?y.message:String(y);q.errors.push(`Icon generation failed: ${V}`),q.success=!1}return q}function n(G){let B=G.sizes||k,q=G.outputDir?`/${G.outputDir}`:"/pwa-icons",K=G.generateWebP??!0,Y=G.generateAppleIcons??!0,Q=[];for(let X of B)if(Q.push(`${q}/icon-${X}x${X}.png`),K)Q.push(`${q}/icon-${X}x${X}.webp`);if(Y){Q.push(`${q}/apple-touch-icon.png`);for(let X of v)Q.push(`${q}/apple-touch-icon-${X}x${X}.png`)}for(let X of I)Q.push(`${q}/favicon-${X}x${X}.png`);return Q.push(`${q}/icon-maskable-512x512.png`),Q}async function O(){try{return await import("sharp"),!0}catch{return!1}}function m(G,B,q,K){let Y=[],Q=K.join(" ");for(let X of G)if(Y.push({src:`${B}/icon-${X}x${X}.png`,sizes:`${X}x${X}`,type:"image/png",purpose:Q}),q)Y.push({src:`${B}/icon-${X}x${X}.webp`,sizes:`${X}x${X}`,type:"image/webp",purpose:Q});return Y}function g(G){return G.map((B)=>({name:B.name,short_name:B.shortName,description:B.description,url:B.url,icons:B.icons?.map((q)=>({src:q.src,sizes:q.sizes,type:q.type}))}))}function h(G){let B=G.pwa?.shareTarget;if(!B?.enabled)return;let q={action:B.action||"/share",method:B.method||"POST",enctype:B.enctype||"multipart/form-data",params:{title:B.params?.title||"title",text:B.params?.text||"text",url:B.params?.url||"url"}};if(B.acceptFiles&&B.acceptFiles.length>0)q.params.files=B.acceptFiles.map((K)=>({name:K.name,accept:K.accept}));return q}function c(G){let B=G.pwa?.fileHandlers;if(!B?.enabled||!B.accept)return;let q=[{action:B.action||"/",accept:B.accept,launch_type:B.launchType||"single-client"}];if(B.icons)q[0].icons=B.icons.map((K)=>({src:K.src,sizes:K.sizes,type:K.type}));return q}function l(G){let B=G.pwa?.protocolHandlers;if(!B||B.length===0)return;return B.map((q)=>({protocol:q.protocol,url:q.url}))}function u(G){let B=G.pwa;if(!B?.enabled||!B.manifest)return null;let{manifest:q,icons:K}=B,Y=K?.sizes||[72,96,128,144,152,192,384,512],Q=K?.outputDir?`/${K.outputDir}`:"/pwa-icons",X=K?.generateWebP??!0,j=K?.purpose||["any","maskable"],J={name:q.name,short_name:q.shortName||q.name,description:q.description,start_url:q.startUrl||"/",display:q.display||"standalone",display_override:q.displayOverride,orientation:q.orientation,theme_color:q.themeColor,background_color:q.backgroundColor,scope:q.scope||"/",lang:q.lang,dir:q.dir,id:q.id,categories:q.categories,icons:m(Y,Q,X,j)};if(q.shortcuts&&q.shortcuts.length>0)J.shortcuts=g(q.shortcuts);if(q.screenshots&&q.screenshots.length>0)J.screenshots=q.screenshots.map((U)=>({src:U.src,sizes:U.sizes,type:U.type,label:U.label,form_factor:U.platform}));let y=h(G);if(y)J.share_target=y;let V=c(G);if(V)J.file_handlers=V;let R=l(G);if(R)J.protocol_handlers=R;if(q.launchHandler)J.launch_handler={client_mode:q.launchHandler};if(q.handleLinks)J.handle_links=q.handleLinks;if(q.edgeSidePanel?.enabled)J.edge_side_panel={preferred_width:q.edgeSidePanel.preferredWidth};return J}function M(G){let B=u(G);if(!B)return"";let q=JSON.parse(JSON.stringify(B));return JSON.stringify(q,null,2)}function i(G,B){return{...B,...G,shortcuts:G.shortcuts||B.shortcuts,screenshots:G.screenshots||B.screenshots,categories:G.categories||B.categories}}function s(G){let B=[],q=G.pwa;if(!q?.enabled)return B;let K=q.manifest;if(!K)return B.push("PWA manifest configuration is missing"),B;if(!K.name)B.push("Manifest name is required");let Y=["fullscreen","standalone","minimal-ui","browser"];if(K.display&&!Y.includes(K.display))B.push(`Invalid display mode: ${K.display}. Must be one of: ${Y.join(", ")}`);let Q=["any","natural","landscape","landscape-primary","landscape-secondary","portrait","portrait-primary","portrait-secondary"];if(K.orientation&&!Q.includes(K.orientation))B.push(`Invalid orientation: ${K.orientation}`);let X=/^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$/;if(K.themeColor&&!X.test(K.themeColor))B.push(`Invalid theme color: ${K.themeColor}. Must be a valid hex color.`);if(K.backgroundColor&&!X.test(K.backgroundColor))B.push(`Invalid background color: ${K.backgroundColor}. Must be a valid hex color.`);if(q.shareTarget?.enabled){if(!q.shareTarget.action)B.push("Share target action URL is required")}if(q.fileHandlers?.enabled){if(!q.fileHandlers.accept||Object.keys(q.fileHandlers.accept).length===0)B.push("File handlers must specify accepted MIME types")}if(q.protocolHandlers)for(let j of q.protocolHandlers){if(!j.protocol)B.push("Protocol handler missing protocol");if(!j.url||!j.url.includes("%s"))B.push(`Protocol handler URL must contain %s placeholder: ${j.protocol}`)}return B}import A from"path";async function b(G){let B=G.pwa?.offline;if(!B?.enabled)return"";if(B.page){let q=A.isAbsolute(B.page)?B.page:A.resolve(process.cwd(),B.page);if(await Bun.file(q).exists())try{let{processDirectives:K}=await import("./chunk-rwa10jm4.js"),Y=await Bun.file(q).text();return await K(Y,{},q,G,new Set)}catch(K){console.warn(`[PWA] Failed to process custom offline page: ${K}`)}else console.warn(`[PWA] Custom offline page not found: ${q}`)}return f(G)}function f(G){let B=G.pwa?.offline,q=G.pwa?.manifest,K=B?.fallbackTitle||"You are offline",Y=B?.fallbackMessage||"Please check your internet connection and try again.",Q=q?.themeColor||"#4f46e5",X=q?.shortName||q?.name||"App";return`<!DOCTYPE html>
+import{Fk as wq,Gk as dq,Hk as Cq,Ik as mq,Jk as gq}from"./chunk-wvc7t11n.js";import{Kk as S,Lk as Tq,Mk as _q,Nk as z,Ok as D,Pk as P,Qk as kq,Rk as vq,Sk as w,Tk as Iq,Uk as d,Vk as Hq,Wk as Oq,Xk as Mq}from"./chunk-c7qdnc5d.js";import{Aw as Sq,Bw as zq,Cw as Dq,Dw as Pq,yw as Aq,zw as bq}from"./chunk-s60eccqk.js";import{Hw as N}from"./chunk-0s3ry262.js";import p from"fs";import E from"path";import C from"fs";import L from"path";var k=[72,96,128,144,152,192,384,512],v=[120,152,167,180],I=[16,32];async function H(G,B){let q={success:!0,generatedFiles:[],errors:[],warnings:[]},K=G.pwa?.icons;if(!K?.src)return q.errors.push("No source icon specified in pwa.icons.src"),q.success=!1,q;let Y=L.isAbsolute(K.src)?K.src:L.resolve(process.cwd(),K.src);if(!await Bun.file(Y).exists())return q.errors.push(`Source icon not found: ${Y}`),q.success=!1,q;let Q=L.resolve(B,K.outputDir||"pwa-icons");try{C.mkdirSync(Q,{recursive:!0})}catch{return q.errors.push(`Failed to create output directory: ${Q}`),q.success=!1,q}let X=K.sizes||k,j=K.generateWebP??!0,J=K.generateAppleIcons??!0;try{let y;try{y=await import("sharp")}catch{return q.errors.push(`sharp is not installed. Install it with: bun add sharp
+Icon generation requires the sharp package for image processing.`),q.success=!1,q}let R=await y.default(Y).metadata();if(R.width&&R.width<512)q.warnings.push(`Source icon is ${R.width}x${R.height}. Recommend using at least 512x512 for best quality.`);for(let $ of X){let x=L.join(Q,`icon-${$}x${$}.png`);if(await y.default(Y).resize($,$,{fit:"contain",background:{r:0,g:0,b:0,alpha:0}}).png().toFile(x),q.generatedFiles.push(x),j){let F=L.join(Q,`icon-${$}x${$}.webp`);await y.default(Y).resize($,$,{fit:"contain",background:{r:0,g:0,b:0,alpha:0}}).webp({quality:90}).toFile(F),q.generatedFiles.push(F)}}if(J){for(let x of v){let F=L.join(Q,`apple-touch-icon-${x}x${x}.png`);await y.default(Y).resize(x,x,{fit:"contain",background:{r:255,g:255,b:255,alpha:1}}).png().toFile(F),q.generatedFiles.push(F)}let $=L.join(Q,"apple-touch-icon.png");await y.default(Y).resize(180,180,{fit:"contain",background:{r:255,g:255,b:255,alpha:1}}).png().toFile($),q.generatedFiles.push($)}for(let $ of I){let x=L.join(Q,`favicon-${$}x${$}.png`);await y.default(Y).resize($,$,{fit:"contain",background:{r:0,g:0,b:0,alpha:0}}).png().toFile(x),q.generatedFiles.push(x)}let U=512,T=L.join(Q,`icon-maskable-${U}x${U}.png`),Z=Math.floor(U*0.1),_=U-Z*2;await y.default(Y).resize(_,_,{fit:"contain",background:{r:0,g:0,b:0,alpha:0}}).extend({top:Z,bottom:Z,left:Z,right:Z,background:{r:255,g:255,b:255,alpha:1}}).png().toFile(T),q.generatedFiles.push(T)}catch(y){let V=y instanceof Error?y.message:String(y);q.errors.push(`Icon generation failed: ${V}`),q.success=!1}return q}function n(G){let B=G.sizes||k,q=G.outputDir?`/${G.outputDir}`:"/pwa-icons",K=G.generateWebP??!0,Y=G.generateAppleIcons??!0,Q=[];for(let X of B)if(Q.push(`${q}/icon-${X}x${X}.png`),K)Q.push(`${q}/icon-${X}x${X}.webp`);if(Y){Q.push(`${q}/apple-touch-icon.png`);for(let X of v)Q.push(`${q}/apple-touch-icon-${X}x${X}.png`)}for(let X of I)Q.push(`${q}/favicon-${X}x${X}.png`);return Q.push(`${q}/icon-maskable-512x512.png`),Q}async function O(){try{return await import("sharp"),!0}catch{return!1}}function m(G,B,q,K){let Y=[],Q=K.join(" ");for(let X of G)if(Y.push({src:`${B}/icon-${X}x${X}.png`,sizes:`${X}x${X}`,type:"image/png",purpose:Q}),q)Y.push({src:`${B}/icon-${X}x${X}.webp`,sizes:`${X}x${X}`,type:"image/webp",purpose:Q});return Y}function g(G){return G.map((B)=>({name:B.name,short_name:B.shortName,description:B.description,url:B.url,icons:B.icons?.map((q)=>({src:q.src,sizes:q.sizes,type:q.type}))}))}function h(G){let B=G.pwa?.shareTarget;if(!B?.enabled)return;let q={action:B.action||"/share",method:B.method||"POST",enctype:B.enctype||"multipart/form-data",params:{title:B.params?.title||"title",text:B.params?.text||"text",url:B.params?.url||"url"}};if(B.acceptFiles&&B.acceptFiles.length>0)q.params.files=B.acceptFiles.map((K)=>({name:K.name,accept:K.accept}));return q}function c(G){let B=G.pwa?.fileHandlers;if(!B?.enabled||!B.accept)return;let q=[{action:B.action||"/",accept:B.accept,launch_type:B.launchType||"single-client"}];if(B.icons)q[0].icons=B.icons.map((K)=>({src:K.src,sizes:K.sizes,type:K.type}));return q}function l(G){let B=G.pwa?.protocolHandlers;if(!B||B.length===0)return;return B.map((q)=>({protocol:q.protocol,url:q.url}))}function u(G){let B=G.pwa;if(!B?.enabled||!B.manifest)return null;let{manifest:q,icons:K}=B,Y=K?.sizes||[72,96,128,144,152,192,384,512],Q=K?.outputDir?`/${K.outputDir}`:"/pwa-icons",X=K?.generateWebP??!0,j=K?.purpose||["any","maskable"],J={name:q.name,short_name:q.shortName||q.name,description:q.description,start_url:q.startUrl||"/",display:q.display||"standalone",display_override:q.displayOverride,orientation:q.orientation,theme_color:q.themeColor,background_color:q.backgroundColor,scope:q.scope||"/",lang:q.lang,dir:q.dir,id:q.id,categories:q.categories,icons:m(Y,Q,X,j)};if(q.shortcuts&&q.shortcuts.length>0)J.shortcuts=g(q.shortcuts);if(q.screenshots&&q.screenshots.length>0)J.screenshots=q.screenshots.map((U)=>({src:U.src,sizes:U.sizes,type:U.type,label:U.label,form_factor:U.platform}));let y=h(G);if(y)J.share_target=y;let V=c(G);if(V)J.file_handlers=V;let R=l(G);if(R)J.protocol_handlers=R;if(q.launchHandler)J.launch_handler={client_mode:q.launchHandler};if(q.handleLinks)J.handle_links=q.handleLinks;if(q.edgeSidePanel?.enabled)J.edge_side_panel={preferred_width:q.edgeSidePanel.preferredWidth};return J}function M(G){let B=u(G);if(!B)return"";let q=JSON.parse(JSON.stringify(B));return JSON.stringify(q,null,2)}function i(G,B){return{...B,...G,shortcuts:G.shortcuts||B.shortcuts,screenshots:G.screenshots||B.screenshots,categories:G.categories||B.categories}}function s(G){let B=[],q=G.pwa;if(!q?.enabled)return B;let K=q.manifest;if(!K)return B.push("PWA manifest configuration is missing"),B;if(!K.name)B.push("Manifest name is required");let Y=["fullscreen","standalone","minimal-ui","browser"];if(K.display&&!Y.includes(K.display))B.push(`Invalid display mode: ${K.display}. Must be one of: ${Y.join(", ")}`);let Q=["any","natural","landscape","landscape-primary","landscape-secondary","portrait","portrait-primary","portrait-secondary"];if(K.orientation&&!Q.includes(K.orientation))B.push(`Invalid orientation: ${K.orientation}`);let X=/^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$/;if(K.themeColor&&!X.test(K.themeColor))B.push(`Invalid theme color: ${K.themeColor}. Must be a valid hex color.`);if(K.backgroundColor&&!X.test(K.backgroundColor))B.push(`Invalid background color: ${K.backgroundColor}. Must be a valid hex color.`);if(q.shareTarget?.enabled){if(!q.shareTarget.action)B.push("Share target action URL is required")}if(q.fileHandlers?.enabled){if(!q.fileHandlers.accept||Object.keys(q.fileHandlers.accept).length===0)B.push("File handlers must specify accepted MIME types")}if(q.protocolHandlers)for(let j of q.protocolHandlers){if(!j.protocol)B.push("Protocol handler missing protocol");if(!j.url||!j.url.includes("%s"))B.push(`Protocol handler URL must contain %s placeholder: ${j.protocol}`)}return B}import A from"path";async function b(G){let B=G.pwa?.offline;if(!B?.enabled)return"";if(B.page){let q=A.isAbsolute(B.page)?B.page:A.resolve(process.cwd(),B.page);if(await Bun.file(q).exists())try{let{processDirectives:K}=await import("./chunk-fytemc96.js"),Y=await Bun.file(q).text();return await K(Y,{},q,G,new Set)}catch(K){console.warn(`[PWA] Failed to process custom offline page: ${K}`)}else console.warn(`[PWA] Custom offline page not found: ${q}`)}return f(G)}function f(G){let B=G.pwa?.offline,q=G.pwa?.manifest,K=B?.fallbackTitle||"You are offline",Y=B?.fallbackMessage||"Please check your internet connection and try again.",Q=q?.themeColor||"#4f46e5",X=q?.shortName||q?.name||"App";return`<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="UTF-8">

package/dist/seo.d.ts

@@ -2,10 +2,15 @@
  * SEO (Search Engine Optimization) Module
  *
  * Provides directives and utilities for generating SEO-related HTML:
- * - `@meta('name', 'content')` - Generate meta tags
+ * - `@meta('name', 'content')` / `@meta('name', expression)` - Generate meta tags
  * - `@metaTag({ name, property, content })` - Meta tags with full control
- * - `@structuredData({ ... })` - JSON-LD structured data
- * - `@seo({ title, description, ... })` - Comprehensive SEO generation
+ * - `@structuredData({ ... })` / `@structuredData(expression)` - JSON-LD structured data
+ * - `@seo({ title, description, ... })` / `@seo(expression)` - Comprehensive SEO generation
+ *
+ * Every argument is an expression evaluated against the template's context, so
+ * a variable, a spread or a function call works wherever a literal does. A
+ * directive that cannot produce its tag says so: an inline comment where the
+ * tag would have been and a console warning naming the file.
  *
  * Also provides:
  * - Automatic SEO tag injection via `injectSeoTags()`
@@ -56,21 +61,36 @@
  */
 import type { CustomDirective, StxOptions } from './types';
 /**
- * Process @meta directive for generating meta tags.
- * Supports both simple `@meta('name', 'content')` and
- * OpenGraph `@meta('og:title')` formats.
+ * Process `@meta(...)` and `@metaTag({...})` in place, emitting the tags where
+ * the directives sit.
+ *
+ * This is the pass a partial's directives go through (a head partial is inside
+ * `<head>` already), and the page-level catch-all for any `@meta` the staging
+ * directive did not take. Arguments are resolved by `resolveMetaArguments`:
+ * `@meta('author', 'Jane')`, `@meta('author', author)`,
+ * `@meta('og:title', post.title)`, and the one-argument `@meta('og:title')`.
  */
-export declare function processMetaDirectives(template: string, context: Record<string, any>, _filePath: string, _options: StxOptions): string;
+export declare function processMetaDirectives(template: string, context: Record<string, any>, filePath: string, _options: StxOptions): string;
 /**
- * Process @structuredData directive for JSON-LD.
- * Automatically adds schema.org context if not provided.
+ * Process `@structuredData(...)` for JSON-LD.
+ *
+ * The argument is any expression that evaluates to an object, or an array of
+ * objects: `@structuredData({ '@type': 'Product', name })`,
+ * `@structuredData(product)`, `@structuredData(buildSchema(post))`. schema.org
+ * is filled in as the `@context` when the data has none.
  */
-export declare function processStructuredData(template: string, context: Record<string, any>, _filePath: string): string;
+export declare function processStructuredData(template: string, context: Record<string, any>, filePath: string): string;
 /**
- * Process @seo directive for automatic meta tag generation.
- * Generates title, description, Open Graph, Twitter, and structured data tags.
+ * Process `@seo(...)` for title, description, Open Graph, Twitter and
+ * structured data tags.
+ *
+ * The argument is any expression that evaluates to an object:
+ * `@seo({ title, description })`, `@seo(seo)`, `@seo({ ...seo, title })`,
+ * `@seo(buildSeo(page))`. `null` or `undefined` from a variable that exists
+ * renders nothing; a variable that does not exist, a value that is not an
+ * object, and keys `@seo` does not read are all reported.
  */
-export declare function processSeoDirective(template: string, context: Record<string, any>, _filePath: string, _options: StxOptions): string;
+export declare function processSeoDirective(template: string, context: Record<string, any>, filePath: string, _options: StxOptions): string;
 /**
  * Injects default SEO tags if no @seo directive is used.
  * Respects seo.enabled config and skipDefaultSeoTags option.
@@ -87,13 +107,15 @@ export declare function injectSeoTags(html: string, context: Record<string, any>
  *
  * This directive shadows `processMetaDirective` in head.ts, since custom
  * directives run first. It therefore has to do that function's job, which is
- * why it resolves unquoted arguments from the context and separates `property`
- * from `name` here rather than leaving it to a later pass that will never see
- * the directive.
+ * why it takes its arguments as written (`rawParams`) and resolves them with
+ * the same `resolveMetaArguments` the other two @meta passes use: a quoted
+ * value is text, anything else is an expression.
  */
 export declare const metaDirective: CustomDirective;
 /**
- * SEO structured data directive for JSON-LD generation
+ * SEO structured data directive for JSON-LD generation, the block form:
+ * `@structuredData { ... } @endstructuredData`. The body is JSON, not an
+ * expression; `@structuredData(expression)` is the form that reads variables.
  */
 export declare const structuredDataDirective: CustomDirective;
 /**