@wcstack/lint 1.26.0 → 1.28.0

package/README.ja.md

@@ -23,6 +23,8 @@ npx wcs-validate --errors-only src/**/*.html
 
 `.manifest.json` で終わるファイルは sidecar manifest として、それ以外は `data-wcs` バインディングを含む HTML として検査されます。
 
+`<wcs-state src="...">` で参照される外部 state（`.json` / `.js` / `.ts`）は HTML ファイルからの相対パスで解決され、パス検証の対象になります。URL・絶対パスは読み込まず、読めないファイルはスキップされ、解決できないパスは warning のままです。なお外部 state が**解決できた**ページには通常の検証面が全て適用されるため、error severity の検出（例: 配列でない値への `for:`）が「これまでパス未解決で沈黙していたビルド」を新たに落とすことがあります。
+
 ```
 wcs-validate [--attr=data-wcs] [--state-tag=wcs-state] [--lang=ja|en] [--errors-only] <file> [<file> ...]
 ```

package/README.md

@@ -23,6 +23,8 @@ npx wcs-validate --errors-only src/**/*.html
 
 Files ending in `.manifest.json` are validated as sidecar manifests; everything else is validated as HTML with `data-wcs` bindings.
 
+External state referenced via `<wcs-state src="...">` (`.json` / `.js` / `.ts`) is resolved relative to the HTML file and included in path validation. URLs and absolute paths are never read, unreadable files are skipped, and unresolved paths stay warnings. Note that once external state *does* resolve, the full validation surface applies to those pages — error-severity findings (e.g. `for:` bound to a non-array) can fail a build that was previously silent because the paths could not be checked.
+
 ```
 wcs-validate [--attr=data-wcs] [--state-tag=wcs-state] [--lang=ja|en] [--errors-only] <file> [<file> ...]
 ```

package/dist/cli.cjs

@@ -21,12 +21,14 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/cli.ts
 var cli_exports = {};
 __export(cli_exports, {
+  createFileReader: () => createFileReader,
   main: () => main,
   parseArgs: () => parseArgs,
   resolveCliLocale: () => resolveCliLocale
 });
 module.exports = __toCommonJS(cli_exports);
 var import_node_fs = require("node:fs");
+var import_node_path = require("node:path");
 
 // src/core/offsetToPosition.ts
 function createPositionMapper(text) {
@@ -89,6 +91,13 @@ var WcsDiagnosticCode = {
   TokenUndeclared: "wcs/token-undeclared",
   TokenMisconfigured: "wcs/token-misconfigured",
   NestedAssign: "wcs/nested-assign",
+  // --- <wcs-state> script: $watch declaration ---
+  // ランタイム（watch/processWatchDeclaration.ts）が raiseError で落とす宣言。
+  // 越境 `@` / `$` 始まり / 空キー・空セグメント / 明らかな非関数ハンドラ。
+  WatchDeclarationInvalid: "wcs/watch-declaration-invalid",
+  // `$watch` のキーが状態定義に存在しない。バインディング側と違い黙って発火しない
+  // だけなので気づけない。severity は binding-path-missing に揃える（warning）。
+  WatchPathMissing: "wcs/watch-path-missing",
   TypeAnnotation: "wcs/type-annotation",
   TemplateSyntax: "wcs/template-syntax",
   // --- <wcs-state> script: array reactivity hazards ---
@@ -134,6 +143,8 @@ var builtinFilterMeta = {
   mul: { description: "\u4E57\u7B97", hasArgs: true, resultType: "number", acceptTypes: ["number"], minArgs: 1, maxArgs: 1, argTypes: ["number"] },
   div: { description: "\u9664\u7B97", hasArgs: true, resultType: "number", acceptTypes: ["number"], minArgs: 1, maxArgs: 1, argTypes: ["number"] },
   mod: { description: "\u5270\u4F59", hasArgs: true, resultType: "number", acceptTypes: ["number"], minArgs: 1, maxArgs: 1, argTypes: ["number"] },
+  abs: { description: "\u7D76\u5BFE\u5024", hasArgs: false, resultType: "number", acceptTypes: ["number"], minArgs: 0, maxArgs: 0 },
+  clamp: { description: "\u7BC4\u56F2\u5185\u306B\u4E38\u3081\u308B (min,max)", hasArgs: true, resultType: "number", acceptTypes: ["number"], minArgs: 2, maxArgs: 2, argTypes: ["number", "number"] },
   // 数値フォーマット
   fix: { description: "\u56FA\u5B9A\u5C0F\u6570\u70B9\u8868\u8A18", hasArgs: true, resultType: "string", acceptTypes: ["number"], minArgs: 0, maxArgs: 1, argTypes: ["number"] },
   locale: { description: "\u30ED\u30B1\u30FC\u30EB\u5F62\u5F0F\u3067\u6570\u5024\u30D5\u30A9\u30FC\u30DE\u30C3\u30C8", hasArgs: true, resultType: "string", acceptTypes: ["number"], minArgs: 0, maxArgs: 1, argTypes: ["string"] },
@@ -147,6 +158,8 @@ var builtinFilterMeta = {
   pad: { description: "\u30D1\u30C7\u30A3\u30F3\u30B0 (length[,char])", hasArgs: true, resultType: "string", acceptTypes: ["string"], minArgs: 1, maxArgs: 2, argTypes: ["number", "string"] },
   rep: { description: "\u7E70\u308A\u8FD4\u3057 (count)", hasArgs: true, resultType: "string", acceptTypes: ["string"], minArgs: 1, maxArgs: 1, argTypes: ["number"] },
   rev: { description: "\u6587\u5B57\u9806\u3092\u53CD\u8EE2", hasArgs: false, resultType: "string", acceptTypes: ["string"], minArgs: 0, maxArgs: 0 },
+  truncate: { description: "\u5207\u308A\u8A70\u3081\u3066\u7701\u7565\u8A18\u53F7 (length[,suffix])", hasArgs: true, resultType: "string", acceptTypes: ["string"], minArgs: 1, maxArgs: 2, argTypes: ["number", "string"] },
+  join: { description: "\u914D\u5217\u3092\u9023\u7D50 ([separator])", hasArgs: true, resultType: "string", acceptTypes: ["array"], minArgs: 0, maxArgs: 1, argTypes: ["string"] },
   // 数値パース・丸め
   int: { description: "\u6574\u6570\u306B\u30D1\u30FC\u30B9", hasArgs: false, resultType: "number", acceptTypes: ["string", "number"], minArgs: 0, maxArgs: 0 },
   float: { description: "\u6D6E\u52D5\u5C0F\u6570\u70B9\u6570\u306B\u30D1\u30FC\u30B9", hasArgs: false, resultType: "number", acceptTypes: ["string", "number"], minArgs: 0, maxArgs: 0 },
@@ -154,11 +167,15 @@ var builtinFilterMeta = {
   floor: { description: "\u5207\u308A\u4E0B\u3052", hasArgs: true, resultType: "number", acceptTypes: ["number"], minArgs: 0, maxArgs: 1, argTypes: ["number"] },
   ceil: { description: "\u5207\u308A\u4E0A\u3052", hasArgs: true, resultType: "number", acceptTypes: ["number"], minArgs: 0, maxArgs: 1, argTypes: ["number"] },
   percent: { description: "\u30D1\u30FC\u30BB\u30F3\u30C6\u30FC\u30B8\u5F62\u5F0F", hasArgs: true, resultType: "string", acceptTypes: ["number"], minArgs: 0, maxArgs: 1, argTypes: ["number"] },
+  // number だけでなく string も受ける。実用チェーンは fix / percent の後ろに繋がり、
+  // それらは既に string を返すため（builtinFilters.ts の unit を参照）
+  unit: { description: "\u5358\u4F4D\uFF08\u63A5\u5C3E\u8F9E\uFF09\u3092\u4ED8\u52A0", hasArgs: true, resultType: "string", acceptTypes: ["number", "string"], minArgs: 1, maxArgs: 1, argTypes: ["string"] },
   // 日付・時刻
   date: { description: "\u30ED\u30B1\u30FC\u30EB\u5F62\u5F0F\u306E\u65E5\u4ED8", hasArgs: false, resultType: "string", acceptTypes: "any", minArgs: 0, maxArgs: 0 },
   time: { description: "\u30ED\u30B1\u30FC\u30EB\u5F62\u5F0F\u306E\u6642\u523B", hasArgs: false, resultType: "string", acceptTypes: "any", minArgs: 0, maxArgs: 0 },
   datetime: { description: "\u30ED\u30B1\u30FC\u30EB\u5F62\u5F0F\u306E\u65E5\u6642", hasArgs: false, resultType: "string", acceptTypes: "any", minArgs: 0, maxArgs: 0 },
   ymd: { description: "YYYY-MM-DD \u5F62\u5F0F", hasArgs: true, resultType: "string", acceptTypes: "any", minArgs: 0, maxArgs: 1, argTypes: ["string"] },
+  hms: { description: "HH:MM:SS \u5F62\u5F0F", hasArgs: true, resultType: "string", acceptTypes: "any", minArgs: 0, maxArgs: 1, argTypes: ["string"] },
   // 真偽値・変換
   falsy: { description: "\u507D\u5024\u304B\u5224\u5B9A", hasArgs: false, resultType: "boolean", acceptTypes: "any", minArgs: 0, maxArgs: 0 },
   truthy: { description: "\u771F\u5024\u304B\u5224\u5B9A", hasArgs: false, resultType: "boolean", acceptTypes: "any", minArgs: 0, maxArgs: 0 },
@@ -175,9 +192,24 @@ var STRUCTURAL_BINDING_TYPE_SET = /* @__PURE__ */ new Set([
   "for"
 ]);
 var MAX_WILDCARD_DEPTH = 128;
+var MODIFIER_PREVENT = "prevent";
+var MODIFIER_STOP = "stop";
+var MODIFIER_READONLY = "ro";
+var MODIFIER_FLAGS = Object.freeze([
+  MODIFIER_PREVENT,
+  MODIFIER_STOP,
+  MODIFIER_READONLY
+]);
+var MODIFIER_KEY_INIT = "init";
+var MODIFIER_KEY_SYNC = "sync";
+var MODIFIER_KEYS = Object.freeze([
+  MODIFIER_KEY_INIT,
+  MODIFIER_KEY_SYNC
+]);
+var INDEX_PARAM_PREFIX = "$";
 var tmpIndexByIndexName = {};
 for (let i = 0; i < MAX_WILDCARD_DEPTH; i++) {
-  tmpIndexByIndexName[`$${i + 1}`] = i;
+  tmpIndexByIndexName[`${INDEX_PARAM_PREFIX}${i + 1}`] = i;
 }
 Object.freeze(tmpIndexByIndexName);
 
@@ -419,6 +451,7 @@ var RESERVED_STREAMS_KEY = "$streams";
 var RESERVED_COMMAND_TOKENS_KEY = "$commandTokens";
 var RESERVED_EVENT_TOKENS_KEY = "$eventTokens";
 var RESERVED_LIST_KEYS_KEY = "$listKeys";
+var RESERVED_WATCH_KEY = "$watch";
 function analyzeStatePaths(scriptContent, stateName = "default") {
   const objectContent = extractDefaultExportObject(scriptContent);
   if (!objectContent) return [];
@@ -452,6 +485,36 @@ function analyzeStatePaths(scriptContent, stateName = "default") {
   }
   return paths;
 }
+function analyzeWatchEntries(scriptContent) {
+  const root = locateDefaultExportObject(scriptContent);
+  if (!root) return [];
+  const watchProp = parseTopLevelProperties(root.content).find((p) => p.name === RESERVED_WATCH_KEY);
+  if (!watchProp || watchProp.kind !== "data" || !watchProp.value || !isObjectLiteral(watchProp.value) || watchProp.valueStart === void 0) {
+    return [];
+  }
+  const leading = watchProp.value.length - watchProp.value.trimStart().length;
+  const innerStart = root.start + watchProp.valueStart + leading + 1;
+  const entries = [];
+  for (const entry of parseTopLevelProperties(extractObjectContent(watchProp.value))) {
+    if (entry.nameStart === void 0 || entry.nameEnd === void 0) continue;
+    entries.push({
+      key: entry.name,
+      start: innerStart + entry.nameStart,
+      end: innerStart + entry.nameEnd,
+      // メソッド短縮記法は関数。data は値リテラルの形で判定し、識別子参照は疑わない。
+      definitelyNotFunction: entry.kind === "data" && isNonFunctionLiteral(entry.value)
+    });
+  }
+  return entries;
+}
+function isNonFunctionLiteral(value) {
+  if (value === void 0) return false;
+  const trimmed = value.trim();
+  if (trimmed.length === 0) return false;
+  const scan = maskCommentsAndStrings(trimmed);
+  if (/^(?:async\s+)?function\b/.test(trimmed) || scan.includes("=>")) return false;
+  return /^["'`]/.test(trimmed) || /^-?\d/.test(trimmed) || /^(?:true|false|null|undefined)\b/.test(trimmed) || trimmed.startsWith("[") || trimmed.startsWith("{");
+}
 function collectReservedKeyPaths(prop, paths, pendingStreamValues, pendingListKeys, stateName) {
   if (prop.name === RESERVED_STREAMS_KEY && prop.kind === "data" && prop.value && isObjectLiteral(prop.value)) {
     const entries = parseTopLevelProperties(extractObjectContent(prop.value));
@@ -598,23 +661,29 @@ function inferJsonTypeHint(value) {
   if (typeof value === "object") return "object";
   return void 0;
 }
-function extractDefaultExportObject(script) {
+function locateDefaultExportObject(script) {
   const scan = maskCommentsAndStrings(script);
   const match = scan.match(/export\s+default\s+(?:defineState\s*\(\s*)?(\{)/);
   if (!match) return null;
-  const startIndex = scan.indexOf(match[1], match.index);
-  return extractBracedContent(script, scan, startIndex);
+  const braceIndex = scan.indexOf(match[1], match.index);
+  return { content: extractBracedContent(script, scan, braceIndex), start: braceIndex + 1 };
+}
+function extractDefaultExportObject(script) {
+  return locateDefaultExportObject(script)?.content ?? null;
 }
 function parseTopLevelProperties(objectContent) {
   const props = [];
   const scan = maskCommentsAndStrings(objectContent);
-  const regex = /(?:(?:get|set)\s+(?:"([^"]+)"|'([^']+)'|([$\w]+))\s*\([^)]*\)\s*\{)|(?:(?:async\s+)?([$\w]+)\s*\([^)]*\)\s*\{)|(?:(?:"([^"]+)"|'([^']+)'|([$\w]+))\s*:\s*)/gd;
+  const regex = /(?:(?:get|set)\s+(?:"([^"]+)"|'([^']+)'|([$\w]+))\s*\([^)]*\)\s*\{)|(?:(?:async\s+)?(?:"([^"]+)"|'([^']+)'|([$\w]+))\s*\([^)]*\)\s*\{)|(?:(?:"([^"]+)"|'([^']+)'|([$\w]+))\s*:\s*)/gd;
   let match;
   while ((match = regex.exec(scan)) !== null) {
     const indices = match.indices;
+    let nameSpan;
     const nameAt = (group) => {
       const span = indices[group];
-      return span ? objectContent.slice(span[0], span[1]) : void 0;
+      if (!span) return void 0;
+      nameSpan = [span[0], span[1]];
+      return objectContent.slice(span[0], span[1]);
     };
     const skipBody = () => {
       const braceStart = match.index + match[0].length - 1;
@@ -623,23 +692,31 @@ function parseTopLevelProperties(objectContent) {
     };
     const accessorName = nameAt(1) ?? nameAt(2) ?? nameAt(3);
     if (accessorName) {
-      props.push({ name: accessorName, kind: "getter" });
+      props.push({ name: accessorName, kind: "getter", nameStart: nameSpan[0], nameEnd: nameSpan[1] });
       skipBody();
       continue;
     }
-    const methodName = nameAt(4);
+    const methodName = nameAt(4) ?? nameAt(5) ?? nameAt(6);
     if (methodName) {
-      props.push({ name: methodName, kind: "method" });
+      props.push({ name: methodName, kind: "method", nameStart: nameSpan[0], nameEnd: nameSpan[1] });
       skipBody();
       continue;
     }
-    const propName = nameAt(5) ?? nameAt(6) ?? nameAt(7);
+    const propName = nameAt(7) ?? nameAt(8) ?? nameAt(9);
     if (propName) {
       const valueStartIndex = match.index + match[0].length;
       const value = extractFullValue(objectContent, scan, valueStartIndex);
       const jsdocType = extractJsDocType(objectContent, match.index);
       const typeHint = jsdocType ?? inferTypeHint(value);
-      props.push({ name: propName, kind: "data", value, typeHint });
+      props.push({
+        name: propName,
+        kind: "data",
+        value,
+        typeHint,
+        nameStart: nameSpan[0],
+        nameEnd: nameSpan[1],
+        valueStart: valueStartIndex
+      });
       regex.lastIndex = valueStartIndex + value.length;
     }
   }
@@ -971,6 +1048,11 @@ var ja = {
   wcsTextInfo: (e) => `wcs-text \u30D0\u30A4\u30F3\u30C7\u30A3\u30F3\u30B0: ${e}`,
   moustacheFouc: (e) => `<template> \u5916\u306E {{ }} \u69CB\u6587\u306F FOUC\uFF08\u521D\u671F\u8868\u793A\u6642\u306B\u30C6\u30F3\u30D7\u30EC\u30FC\u30C8\u6587\u5B57\u5217\u304C\u898B\u3048\u308B\uFF09\u306E\u539F\u56E0\u306B\u306A\u308A\u307E\u3059\u3002<!--@@:${e}--> \u307E\u305F\u306F\u30B3\u30E1\u30F3\u30C8\u69CB\u6587\u306E\u4F7F\u7528\u3092\u691C\u8A0E\u3057\u3066\u304F\u3060\u3055\u3044\u3002`,
   nestedAssign: (sp) => `\u30CD\u30B9\u30C8\u3055\u308C\u305F\u30D7\u30ED\u30D1\u30C6\u30A3\u3078\u306E\u4EE3\u5165\u306F\u30EA\u30A2\u30AF\u30C6\u30A3\u30D6\u66F4\u65B0\u3092\u30C8\u30EA\u30AC\u30FC\u3057\u307E\u305B\u3093\u3002this["${sp}"] \u3092\u4F7F\u7528\u3057\u3066\u304F\u3060\u3055\u3044\u3002`,
+  watchKeyCrossState: (k) => `$watch \u306E\u30AD\u30FC "${k}" \u306F\u4ED6\u306E state \u3092\u6307\u3057\u3066\u3044\u307E\u3059\u3002@ \u4ED8\u304D\u306E\u8D8A\u5883 watch \u306F\u4F7F\u3048\u307E\u305B\u3093\uFF08\u81EA state \u306E\u30D1\u30B9\u306E\u307F\uFF09`,
+  watchKeyReserved: (k) => `$watch \u306E\u30AD\u30FC "${k}" \u306F "$" \u3067\u59CB\u3081\u3089\u308C\u307E\u305B\u3093\uFF08\u4E88\u7D04\u540D\u524D\u7A7A\u9593\uFF09`,
+  watchKeyEmptySegment: (k) => `$watch \u306E\u30AD\u30FC "${k}" \u306B\u7A7A\u306E\u30D1\u30B9\u30BB\u30B0\u30E1\u30F3\u30C8\u304C\u3042\u308A\u307E\u3059`,
+  watchHandlerNotFunction: (k) => `$watch \u306E\u30A8\u30F3\u30C8\u30EA "${k}" \u306E\u5024\u306F\u95A2\u6570\u3067\u3042\u308B\u5FC5\u8981\u304C\u3042\u308A\u307E\u3059`,
+  watchPathMissing: (k) => `$watch \u306E\u30AD\u30FC "${k}" \u306F\u72B6\u614B\u5B9A\u7FA9\u306B\u5B58\u5728\u3057\u307E\u305B\u3093\uFF08\u4E00\u5EA6\u3082\u767A\u706B\u3057\u307E\u305B\u3093\uFF09`,
   typeAnnotationIncompatible: (vt, rt) => `\u578B "${vt}" \u306F @type {${rt}} \u3068\u4E92\u63DB\u6027\u304C\u3042\u308A\u307E\u305B\u3093`,
   arrayMutation: (m, alt) => `\u914D\u5217\u306E\u7834\u58CA\u7684\u30E1\u30BD\u30C3\u30C9 "${m}" \u306F\u30EA\u30A2\u30AF\u30C6\u30A3\u30D6\u66F4\u65B0\u3092\u30C8\u30EA\u30AC\u30FC\u3057\u307E\u305B\u3093\uFF08\u540C\u4E00\u53C2\u7167\u306E\u81EA\u5DF1\u518D\u4EE3\u5165\u3067\u3082\u8981\u7D20\u306E\u8FFD\u52A0\u30FB\u524A\u9664\u306F\u53CD\u6620\u3055\u308C\u307E\u305B\u3093\uFF09\u3002\u975E\u7834\u58CA\u30E1\u30BD\u30C3\u30C9\u3068\u518D\u4EE3\u5165\u3092\u4F7F\u7528\u3057\u3066\u304F\u3060\u3055\u3044\uFF08\u4F8B: ${alt}\uFF09\u3002`,
   arrayIndexAssign: (sp) => `\u914D\u5217\u30A4\u30F3\u30C7\u30C3\u30AF\u30B9\u3078\u306E\u76F4\u63A5\u4EE3\u5165\u306F\u30EA\u30A2\u30AF\u30C6\u30A3\u30D6\u66F4\u65B0\u3092\u30C8\u30EA\u30AC\u30FC\u3057\u307E\u305B\u3093\u3002this["${sp}"] \u306E\u3088\u3046\u306A\u30C9\u30C3\u30C8\u30D1\u30B9\u4EE3\u5165\u3001\u307E\u305F\u306F with() \u3068\u518D\u4EE3\u5165\u3092\u4F7F\u7528\u3057\u3066\u304F\u3060\u3055\u3044\u3002`,
@@ -1013,6 +1095,11 @@ var en = {
   wcsTextInfo: (e) => `wcs-text binding: ${e}`,
   moustacheFouc: (e) => `{{ }} outside a <template> causes FOUC (the raw template string is visible before binding). Consider the comment syntax <!--@@:${e}--> instead.`,
   nestedAssign: (sp) => `Assigning to a nested property does not trigger a reactive update. Use this["${sp}"] instead.`,
+  watchKeyCrossState: (k) => `$watch key "${k}" targets another state. Cross-state watching with @ is not supported (own paths only)`,
+  watchKeyReserved: (k) => `$watch key "${k}" must not start with "$" (reserved namespace)`,
+  watchKeyEmptySegment: (k) => `$watch key "${k}" has an empty path segment`,
+  watchHandlerNotFunction: (k) => `The value of $watch entry "${k}" must be a function`,
+  watchPathMissing: (k) => `$watch key "${k}" does not exist in the state definition (it will never fire)`,
   typeAnnotationIncompatible: (vt, rt) => `Type "${vt}" is not compatible with @type {${rt}}`,
   arrayMutation: (m, alt) => `Destructive array method "${m}" does not trigger a reactive update (re-assigning the same reference does not reflect added/removed elements either). Use a non-destructive method with reassignment (e.g. ${alt}).`,
   arrayIndexAssign: (sp) => `Assigning directly to an array index does not trigger a reactive update. Use a dot-path assignment like this["${sp}"], or with() plus reassignment.`,
@@ -1034,10 +1121,10 @@ function getMessages(locale) {
 
 // src/service/bindingValidator.ts
 var filterMap = new Map(BUILTIN_FILTERS.map((f) => [f.name, f]));
-function validateBindings(html, attrName, stateTagName = "wcs-state", locale) {
+function validateBindings(html, attrName, stateTagName = "wcs-state", locale, fileReader) {
   const diagnostics = [];
   const msgs = getMessages(locale);
-  const statePaths = getStatePathsFromHtml(html, stateTagName);
+  const statePaths = getStatePathsFromHtml(html, stateTagName, fileReader);
   const pathsByState = /* @__PURE__ */ new Map();
   for (const p of statePaths) {
     const list = pathsByState.get(p.stateName) ?? [];
@@ -1828,10 +1915,10 @@ function isInsideTag(html, offset, tagName) {
 }
 
 // src/service/templateSyntaxValidator.ts
-function validateTemplateSyntax(html, stateTagName, bindAttrName = "data-wcs", locale) {
+function validateTemplateSyntax(html, stateTagName, bindAttrName = "data-wcs", locale, fileReader) {
   const diagnostics = [];
   const msgs = getMessages(locale);
-  const allPaths = getStatePathsFromHtml(html, stateTagName);
+  const allPaths = getStatePathsFromHtml(html, stateTagName, fileReader);
   if (allPaths.length === 0) return diagnostics;
   const defaultPaths = allPaths.filter((p) => p.stateName === "default");
   const pathSet = new Set(defaultPaths.map((p) => p.path));
@@ -1945,6 +2032,7 @@ function isValidTemplatePath(path, pathSet, scopedPaths) {
 var BUILTIN_TAGS = {
   "wcs-accelerometer": {
     "package": "accelerometer",
+    "observedAttributes": [],
     "inputs": {
       "frequency": null
     },
@@ -1962,6 +2050,7 @@ var BUILTIN_TAGS = {
   },
   "wcs-ambient-light-sensor": {
     "package": "ambient-light-sensor",
+    "observedAttributes": [],
     "inputs": {
       "frequency": null
     },
@@ -1975,8 +2064,240 @@ var BUILTIN_TAGS = {
       "stop"
     ]
   },
+  "wcs-audio": {
+    "package": "audio",
+    "observedAttributes": [
+      "volume",
+      "limiter",
+      "resume-on-gesture"
+    ],
+    "inputs": {
+      "volume": "volume",
+      "limiter": "limiter",
+      "resumeOnGesture": "resume-on-gesture"
+    },
+    "properties": [
+      "state",
+      "running",
+      "suspended",
+      "unsupported",
+      "voices",
+      "noteOn",
+      "noteOff",
+      "warnings",
+      "error",
+      "errorInfo"
+    ],
+    "commands": [
+      "resume",
+      "suspend",
+      "noteOn",
+      "noteOff",
+      "allNotesOff"
+    ]
+  },
+  "wcs-voice": {
+    "package": "audio",
+    "observedAttributes": [
+      "poly"
+    ],
+    "inputs": {},
+    "properties": [],
+    "commands": []
+  },
+  "wcs-osc": {
+    "package": "audio",
+    "observedAttributes": [
+      "frequency",
+      "detune",
+      "type",
+      "glide",
+      "transpose",
+      "id",
+      "out",
+      "param",
+      "note",
+      "master",
+      "poly"
+    ],
+    "inputs": {
+      "frequency": "frequency",
+      "detune": "detune",
+      "type": "type",
+      "glide": "glide",
+      "transpose": "transpose"
+    },
+    "properties": [],
+    "commands": []
+  },
+  "wcs-noise": {
+    "package": "audio",
+    "observedAttributes": [
+      "id",
+      "out",
+      "param",
+      "note",
+      "master",
+      "poly"
+    ],
+    "inputs": {},
+    "properties": [],
+    "commands": []
+  },
+  "wcs-biquad": {
+    "package": "audio",
+    "observedAttributes": [
+      "frequency",
+      "q",
+      "gain",
+      "detune",
+      "type",
+      "id",
+      "out",
+      "param",
+      "note",
+      "master",
+      "poly"
+    ],
+    "inputs": {
+      "frequency": "frequency",
+      "q": "q",
+      "gain": "gain",
+      "detune": "detune",
+      "type": "type"
+    },
+    "properties": [],
+    "commands": []
+  },
+  "wcs-gain": {
+    "package": "audio",
+    "observedAttributes": [
+      "gain",
+      "id",
+      "out",
+      "param",
+      "note",
+      "master",
+      "poly"
+    ],
+    "inputs": {
+      "gain": "gain"
+    },
+    "properties": [],
+    "commands": []
+  },
+  "wcs-delay": {
+    "package": "audio",
+    "observedAttributes": [
+      "time",
+      "feedback",
+      "mix",
+      "id",
+      "out",
+      "param",
+      "note",
+      "master",
+      "poly"
+    ],
+    "inputs": {
+      "time": "time",
+      "feedback": "feedback",
+      "mix": "mix"
+    },
+    "properties": [],
+    "commands": []
+  },
+  "wcs-shaper": {
+    "package": "audio",
+    "observedAttributes": [
+      "amount",
+      "id",
+      "out",
+      "param",
+      "note",
+      "master",
+      "poly"
+    ],
+    "inputs": {
+      "amount": "amount"
+    },
+    "properties": [],
+    "commands": []
+  },
+  "wcs-env": {
+    "package": "audio",
+    "observedAttributes": [
+      "attack",
+      "decay",
+      "sustain",
+      "release",
+      "depth",
+      "id",
+      "out",
+      "param",
+      "note",
+      "master",
+      "poly"
+    ],
+    "inputs": {
+      "attack": "attack",
+      "decay": "decay",
+      "sustain": "sustain",
+      "release": "release",
+      "depth": "depth"
+    },
+    "properties": [],
+    "commands": []
+  },
+  "wcs-lfo": {
+    "package": "audio",
+    "observedAttributes": [
+      "rate",
+      "depth",
+      "type",
+      "id",
+      "out",
+      "param",
+      "note",
+      "master",
+      "poly"
+    ],
+    "inputs": {
+      "rate": "rate",
+      "depth": "depth",
+      "type": "type"
+    },
+    "properties": [],
+    "commands": []
+  },
+  "wcs-analyser": {
+    "package": "audio",
+    "observedAttributes": [
+      "fft",
+      "smoothing",
+      "id",
+      "out",
+      "param",
+      "note",
+      "master",
+      "poly"
+    ],
+    "inputs": {
+      "fft": "fft",
+      "smoothing": "smoothing"
+    },
+    "properties": [
+      "frame"
+    ],
+    "commands": [
+      "sample"
+    ]
+  },
   "wcs-broadcast": {
     "package": "broadcast",
+    "observedAttributes": [
+      "name"
+    ],
     "inputs": {
       "name": "name",
       "manual": "manual"
@@ -1994,6 +2315,13 @@ var BUILTIN_TAGS = {
   },
   "wcs-camera": {
     "package": "camera",
+    "observedAttributes": [
+      "facing-mode",
+      "device-id",
+      "audio",
+      "width",
+      "height"
+    ],
     "inputs": {
       "audio": "audio",
       "facingMode": "facing-mode",
@@ -2022,6 +2350,7 @@ var BUILTIN_TAGS = {
   },
   "wcs-recorder": {
     "package": "camera",
+    "observedAttributes": [],
     "inputs": {
       "mimeType": "mime-type",
       "timeslice": "timeslice",
@@ -2050,6 +2379,7 @@ var BUILTIN_TAGS = {
   },
   "wcs-clipboard": {
     "package": "clipboard",
+    "observedAttributes": [],
     "inputs": {
       "monitor": "monitor"
     },
@@ -2077,6 +2407,7 @@ var BUILTIN_TAGS = {
   },
   "wcs-contacts": {
     "package": "contacts",
+    "observedAttributes": [],
     "inputs": {},
     "properties": [
       "value",
@@ -2091,6 +2422,7 @@ var BUILTIN_TAGS = {
   },
   "wcs-credential": {
     "package": "credential",
+    "observedAttributes": [],
     "inputs": {},
     "properties": [
       "value",
@@ -2106,6 +2438,7 @@ var BUILTIN_TAGS = {
   },
   "wcs-debounce": {
     "package": "debounce",
+    "observedAttributes": [],
     "inputs": {
       "source": null,
       "wait": "wait",
@@ -2126,6 +2459,7 @@ var BUILTIN_TAGS = {
   },
   "wcs-throttle": {
     "package": "debounce",
+    "observedAttributes": [],
     "inputs": {
       "source": null,
       "wait": "wait",
@@ -2146,6 +2480,7 @@ var BUILTIN_TAGS = {
   },
   "wcs-defined": {
     "package": "defined",
+    "observedAttributes": [],
     "inputs": {
       "tags": "tags",
       "mode": "mode",
@@ -2163,6 +2498,7 @@ var BUILTIN_TAGS = {
   },
   "wcs-eyedropper": {
     "package": "eyedropper",
+    "observedAttributes": [],
     "inputs": {},
     "properties": [
       "value",
@@ -2178,6 +2514,9 @@ var BUILTIN_TAGS = {
   },
   "wcs-fetch": {
     "package": "fetch",
+    "observedAttributes": [
+      "url"
+    ],
     "inputs": {
       "url": null,
       "method": null,
@@ -2203,24 +2542,36 @@ var BUILTIN_TAGS = {
   },
   "wcs-fetch-header": {
     "package": "fetch",
+    "observedAttributes": [],
     "inputs": {},
     "properties": [],
     "commands": []
   },
   "wcs-fetch-body": {
     "package": "fetch",
+    "observedAttributes": [],
     "inputs": {},
     "properties": [],
     "commands": []
   },
   "wcs-infinite-scroll": {
     "package": "fetch",
+    "observedAttributes": [
+      "target",
+      "root",
+      "root-margin",
+      "threshold",
+      "disabled"
+    ],
     "inputs": {},
     "properties": [],
     "commands": []
   },
   "wcs-fullscreen": {
     "package": "fullscreen",
+    "observedAttributes": [
+      "target"
+    ],
     "inputs": {
       "target": "target"
     },
@@ -2236,6 +2587,7 @@ var BUILTIN_TAGS = {
   },
   "wcs-geo": {
     "package": "geolocation",
+    "observedAttributes": [],
     "inputs": {
       "highAccuracy": "high-accuracy",
       "timeout": "timeout",
@@ -2266,6 +2618,7 @@ var BUILTIN_TAGS = {
   },
   "wcs-gyroscope": {
     "package": "gyroscope",
+    "observedAttributes": [],
     "inputs": {
       "frequency": null
     },
@@ -2283,6 +2636,7 @@ var BUILTIN_TAGS = {
   },
   "wcs-idle": {
     "package": "idle",
+    "observedAttributes": [],
     "inputs": {
       "threshold": "threshold"
     },
@@ -2301,6 +2655,12 @@ var BUILTIN_TAGS = {
   },
   "wcs-intersect": {
     "package": "intersection",
+    "observedAttributes": [
+      "target",
+      "root",
+      "root-margin",
+      "threshold"
+    ],
     "inputs": {
       "target": "target",
       "root": "root",
@@ -2328,6 +2688,7 @@ var BUILTIN_TAGS = {
   },
   "wcs-magnetometer": {
     "package": "magnetometer",
+    "observedAttributes": [],
     "inputs": {
       "frequency": null
     },
@@ -2343,8 +2704,46 @@ var BUILTIN_TAGS = {
       "stop"
     ]
   },
+  "wcs-midi": {
+    "package": "midi",
+    "observedAttributes": [
+      "input",
+      "output",
+      "channel"
+    ],
+    "inputs": {
+      "input": "input",
+      "output": "output",
+      "channel": "channel",
+      "sysex": "sysex",
+      "auto": "auto"
+    },
+    "properties": [
+      "message",
+      "type",
+      "channel",
+      "note",
+      "velocity",
+      "control",
+      "value",
+      "devices",
+      "connected",
+      "permission",
+      "granted",
+      "denied",
+      "unsupported",
+      "error",
+      "errorInfo"
+    ],
+    "commands": [
+      "request",
+      "close",
+      "send"
+    ]
+  },
   "wcs-network": {
     "package": "network",
+    "observedAttributes": [],
     "inputs": {},
     "properties": [
       "effectiveType",
@@ -2357,6 +2756,7 @@ var BUILTIN_TAGS = {
   },
   "wcs-notify": {
     "package": "notification",
+    "observedAttributes": [],
     "inputs": {
       "notice": null,
       "mode": "mode",
@@ -2392,6 +2792,7 @@ var BUILTIN_TAGS = {
   },
   "wcs-permission": {
     "package": "permission",
+    "observedAttributes": [],
     "inputs": {
       "name": "name",
       "userVisibleOnly": "user-visible-only",
@@ -2408,6 +2809,9 @@ var BUILTIN_TAGS = {
   },
   "wcs-pip": {
     "package": "picture-in-picture",
+    "observedAttributes": [
+      "target"
+    ],
     "inputs": {
       "target": "target"
     },
@@ -2423,6 +2827,9 @@ var BUILTIN_TAGS = {
   },
   "wcs-pointer-lock": {
     "package": "pointer-lock",
+    "observedAttributes": [
+      "target"
+    ],
     "inputs": {
       "target": "target"
     },
@@ -2438,6 +2845,7 @@ var BUILTIN_TAGS = {
   },
   "wcs-raf": {
     "package": "raf",
+    "observedAttributes": [],
     "inputs": {
       "once": "once",
       "repeat": "repeat",
@@ -2462,6 +2870,11 @@ var BUILTIN_TAGS = {
   },
   "wcs-resize": {
     "package": "resize",
+    "observedAttributes": [
+      "target",
+      "box",
+      "round"
+    ],
     "inputs": {
       "target": "target",
       "box": "box",
@@ -2485,6 +2898,7 @@ var BUILTIN_TAGS = {
   },
   "wcs-screen-orientation": {
     "package": "screen-orientation",
+    "observedAttributes": [],
     "inputs": {},
     "properties": [
       "type",
@@ -2501,6 +2915,7 @@ var BUILTIN_TAGS = {
   },
   "wcs-share": {
     "package": "share",
+    "observedAttributes": [],
     "inputs": {},
     "properties": [
       "value",
@@ -2515,6 +2930,7 @@ var BUILTIN_TAGS = {
   },
   "wcs-speak": {
     "package": "speech",
+    "observedAttributes": [],
     "inputs": {
       "say": null,
       "rate": "rate",
@@ -2544,6 +2960,7 @@ var BUILTIN_TAGS = {
   },
   "wcs-listen": {
     "package": "speech",
+    "observedAttributes": [],
     "inputs": {
       "lang": "lang",
       "continuous": "continuous",
@@ -2571,6 +2988,9 @@ var BUILTIN_TAGS = {
   },
   "wcs-sse": {
     "package": "sse",
+    "observedAttributes": [
+      "url"
+    ],
     "inputs": {
       "url": "url",
       "withCredentials": "with-credentials",
@@ -2595,6 +3015,10 @@ var BUILTIN_TAGS = {
   },
   "wcs-storage": {
     "package": "storage",
+    "observedAttributes": [
+      "key",
+      "type"
+    ],
     "inputs": {
       "key": null,
       "type": null,
@@ -2617,6 +3041,7 @@ var BUILTIN_TAGS = {
   },
   "wcs-tilt": {
     "package": "tilt",
+    "observedAttributes": [],
     "inputs": {},
     "properties": [
       "alpha",
@@ -2635,6 +3060,9 @@ var BUILTIN_TAGS = {
   },
   "wcs-timer": {
     "package": "timer",
+    "observedAttributes": [
+      "interval"
+    ],
     "inputs": {
       "interval": "interval",
       "once": "once",
@@ -2659,6 +3087,9 @@ var BUILTIN_TAGS = {
   },
   "wcs-upload": {
     "package": "upload",
+    "observedAttributes": [
+      "url"
+    ],
     "inputs": {
       "url": null,
       "method": null,
@@ -2687,6 +3118,10 @@ var BUILTIN_TAGS = {
   },
   "wcs-wakelock": {
     "package": "wakelock",
+    "observedAttributes": [
+      "active",
+      "type"
+    ],
     "inputs": {
       "active": "active",
       "type": "type",
@@ -2704,6 +3139,9 @@ var BUILTIN_TAGS = {
   },
   "wcs-ws": {
     "package": "websocket",
+    "observedAttributes": [
+      "url"
+    ],
     "inputs": {
       "url": "url",
       "protocols": "protocols",
@@ -2733,6 +3171,9 @@ var BUILTIN_TAGS = {
   },
   "wcs-worker": {
     "package": "worker",
+    "observedAttributes": [
+      "src"
+    ],
     "inputs": {
       "src": "src",
       "type": "type",
@@ -2774,13 +3215,13 @@ var DOM_COMMON_PROPERTIES = /* @__PURE__ */ new Set([
 ]);
 var STRUCTURAL_DIRECTIVES2 = /* @__PURE__ */ new Set(["for", "if", "elseif", "else"]);
 var EMPTYISH_SEEDS = /* @__PURE__ */ new Set(["''", '""', "``", "null", "[]", "{}"]);
-function validateIoNodes(html, bindAttribute = "data-wcs", stateTagName = "wcs-state", locale) {
+function validateIoNodes(html, bindAttribute = "data-wcs", stateTagName = "wcs-state", locale, fileReader) {
   const diagnostics = [];
   const msgs = getMessages(locale);
   const occurrences = findBuiltinTagOccurrences(html);
   if (occurrences.length === 0) return diagnostics;
   let statePaths = null;
-  const getPaths = () => statePaths ??= getStatePathsFromHtml(html, stateTagName);
+  const getPaths = () => statePaths ??= getStatePathsFromHtml(html, stateTagName, fileReader);
   for (const occ of occurrences) {
     const contract = BUILTIN_TAGS[occ.tagName];
     if (contract.properties.length === 0 && contract.commands.length === 0 && Object.keys(contract.inputs).length === 0) continue;
@@ -3078,17 +3519,68 @@ function blankJsComments(code) {
   return code.replace(/\/\*[\s\S]*?\*\//g, (m) => " ".repeat(m.length)).replace(/(^|[^:])\/\/[^\n]*/g, (m, pre) => pre + " ".repeat(m.length - pre.length));
 }
 
+// src/service/watchDeclarationValidator.ts
+var STATE_NAME_SEPARATOR = "@";
+function validateWatchDeclarations(html, stateTagName = "wcs-state", locale) {
+  const msgs = getMessages(locale);
+  const out = [];
+  for (const block of parseWcsScriptBlocks(html, stateTagName)) {
+    const entries = analyzeWatchEntries(block.content);
+    if (entries.length === 0) continue;
+    const paths = analyzeStatePaths(block.content, block.stateName);
+    const pathSet = new Set(paths.map((p) => p.path));
+    for (const entry of entries) {
+      const diagnostic = validateEntry(entry, pathSet, msgs);
+      if (diagnostic === null) continue;
+      out.push({
+        code: diagnostic.code,
+        start: block.contentStart + entry.start,
+        end: block.contentStart + entry.end,
+        message: diagnostic.message,
+        severity: diagnostic.severity
+      });
+    }
+  }
+  return out;
+}
+function validateEntry(entry, pathSet, msgs) {
+  const { key } = entry;
+  const invalid = (message) => ({ code: WcsDiagnosticCode.WatchDeclarationInvalid, message, severity: "error" });
+  if (key.includes(STATE_NAME_SEPARATOR)) {
+    return invalid(msgs.watchKeyCrossState(key));
+  }
+  if (key.startsWith("$")) {
+    return invalid(msgs.watchKeyReserved(key));
+  }
+  if (key.split(".").some((segment) => segment.length === 0)) {
+    return invalid(msgs.watchKeyEmptySegment(key));
+  }
+  if (entry.definitelyNotFunction) {
+    return invalid(msgs.watchHandlerNotFunction(key));
+  }
+  if (pathSet.size > 0 && !pathSet.has(key)) {
+    return {
+      code: WcsDiagnosticCode.WatchPathMissing,
+      message: msgs.watchPathMissing(key),
+      severity: "warning"
+    };
+  }
+  return null;
+}
+
 // src/core/validateDocument.ts
 function validateDocument(text, options = {}) {
   const bindAttribute = options.bindAttribute ?? "data-wcs";
   const stateTagName = options.stateTagName ?? "wcs-state";
   const locale = options.locale;
+  const fileReader = options.fileReader;
   const out = [];
-  out.push(...validateBindings(text, bindAttribute, stateTagName, locale));
-  out.push(...validateTemplateSyntax(text, stateTagName, bindAttribute, locale));
-  out.push(...validateIoNodes(text, bindAttribute, stateTagName, locale));
+  out.push(...validateBindings(text, bindAttribute, stateTagName, locale, fileReader));
+  out.push(...validateTemplateSyntax(text, stateTagName, bindAttribute, locale, fileReader));
+  out.push(...validateIoNodes(text, bindAttribute, stateTagName, locale, fileReader));
   out.push(...validateDocumentEnv(text, locale));
   out.push(...validateArrayMutations(text, stateTagName, locale));
+  out.push(...validateWatchDeclarations(text, stateTagName, locale));
   for (const d of validateStateTypes(text, stateTagName, locale)) {
     out.push({ code: WcsDiagnosticCode.TypeAnnotation, start: d.start, end: d.end, message: d.message, severity: d.severity });
   }
@@ -3672,7 +4164,8 @@ function runValidation(inputs, options = {}) {
   const diagnosticsBySource = /* @__PURE__ */ new Map();
   for (const input of inputs) {
     if (input.kind === "html") {
-      diagnosticsBySource.set(input.source, validateDocument(input.text, options));
+      const docOptions = input.fileReader !== void 0 ? { ...options, fileReader: input.fileReader } : options;
+      diagnosticsBySource.set(input.source, validateDocument(input.text, docOptions));
     }
   }
   const manifestInputs = inputs.filter((i) => i.kind === "manifest");
@@ -3716,6 +4209,29 @@ function runValidation(inputs, options = {}) {
 function classify(path) {
   return path.endsWith(".manifest.json") ? "manifest" : "html";
 }
+function createFileReader(htmlPath, read = (p) => (0, import_node_fs.readFileSync)(p, "utf8")) {
+  const base = (0, import_node_path.dirname)(htmlPath);
+  const cache = /* @__PURE__ */ new Map();
+  return (relativePath) => {
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(relativePath) || relativePath.startsWith("/")) {
+      return void 0;
+    }
+    if (cache.has(relativePath)) {
+      return cache.get(relativePath);
+    }
+    let content;
+    try {
+      content = read((0, import_node_path.resolve)(base, relativePath));
+      if (content.charCodeAt(0) === 65279) {
+        content = content.slice(1);
+      }
+    } catch {
+      content = void 0;
+    }
+    cache.set(relativePath, content);
+    return content;
+  };
+}
 function parseArgs(argv) {
   const options = {};
   const files = [];
@@ -3755,7 +4271,8 @@ function main(argv) {
 `);
       return 2;
     }
-    inputs.push({ source: path, text, kind: classify(path) });
+    const kind = classify(path);
+    inputs.push({ source: path, text, kind, fileReader: kind === "html" ? createFileReader(path) : void 0 });
   }
   const result = runValidation(inputs, { ...options, locale });
   for (const line of result.lines) {
@@ -3773,6 +4290,7 @@ if (typeof require !== "undefined" && typeof module !== "undefined" && require.m
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  createFileReader,
   main,
   parseArgs,
   resolveCliLocale

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wcstack/lint",
-  "version": "1.26.0",
+  "version": "1.28.0",
   "description": "Static-contract validator CLI (wcs-validate) for wcstack data-wcs bindings and wcstack.manifest.json sidecars. Thin npm wrapper around the wcstack-intellisense validator core.",
   "type": "module",
   "bin": {