@jxsuite/studio 0.23.2 → 0.24.0

package/src/panels/{properties-panel.js → properties-panel.ts}

@@ -1,8 +1,10 @@
+/// <reference lib="dom" />
 /** Properties panel — inspector for element attributes, component props, media, and frontmatter. */
 
 import { html, nothing } from "lit-html";
 import { live } from "lit-html/directives/live.js";
-import { getNodeAtPath, debouncedStyleCommit, renderOnly, projectState } from "../store.js";
+import { getNodeAtPath, debouncedStyleCommit, renderOnly, projectState } from "../store";
+import type { JsonValue, DirEntry } from "../types";
 import {
   transactDoc,
   mutateUpdateProperty,
@@ -12,39 +14,58 @@ import {
   mutateAddSwitchCase,
   mutateRemoveSwitchCase,
   mutateRenameSwitchCase,
-} from "../tabs/transact.js";
-import { activeTab } from "../workspace/workspace.js";
-import { view } from "../view.js";
-import { componentRegistry } from "../files/components.js";
-import { widgetForType } from "./style-inputs.js";
-import { renderFieldRow } from "../ui/field-row.js";
+} from "../tabs/transact";
+import { activeTab } from "../workspace/workspace";
+import { view } from "../view";
+import { componentRegistry } from "../files/components";
+import { widgetForType } from "./style-inputs";
+import { renderFieldRow } from "../ui/field-row";
 import {
   attrLabel,
   inferInputType,
   friendlyNameToVar,
   camelToLabel,
   parseCemType,
-} from "../utils/studio-utils.js";
-import { isCustomElementDoc, collectCssParts } from "./signals-panel.js";
-import { mediaDisplayName } from "./shared.js";
-import { getCssInitialMap } from "./style-utils.js";
-import { renderMediaPicker } from "../ui/media-picker.js";
-import { renderColorSelector } from "../ui/color-selector.js";
-import { getEffectiveLayoutPath, invalidateLayoutCache } from "../site-context.js";
-import { getPlatform } from "../platform.js";
+} from "../utils/studio-utils";
+import { isCustomElementDoc, collectCssParts } from "./signals-panel";
+import { mediaDisplayName } from "./shared";
+import { getCssInitialMap } from "./style-utils";
+import { renderMediaPicker } from "../ui/media-picker";
+import { renderColorSelector } from "../ui/color-selector";
+import { getEffectiveLayoutPath, invalidateLayoutCache } from "../site-context";
+import { getPlatform } from "../platform";
 import htmlMeta from "../../data/html-meta.json";
 
+import type { JxPrototypeDef, JxMutableNode } from "@jxsuite/schema/types";
+import type { JxPath } from "../state";
+
+interface SignalOption {
+  value: string;
+  label: string;
+}
+
+interface HtmlMetaEntry {
+  $section: string;
+  $order: number;
+  $elements?: string[];
+  $label?: string;
+  $input?: string;
+  $shorthand?: boolean;
+  type?: string;
+  [key: string]: unknown;
+}
+
 /**
  * Convert a human-friendly name like "Tablet" to a $media key "--tablet"
  *
  * @param {string} name
  */
-function friendlyNameToMedia(name) {
+function friendlyNameToMedia(name: string) {
   return friendlyNameToVar(name, "--");
 }
 
 /** Check if a selection path is inside a $map template (contains [..., "children", "map", ...]). */
-function isInsideMapTemplate(/** @type {JxPath | null} */ path) {
+function isInsideMapTemplate(path: JxPath | null) {
   if (!path) return false;
   for (let i = 0; i < path.length - 1; i++) {
     if (path[i] === "children" && path[i + 1] === "map") return true;
@@ -56,42 +77,30 @@ function isInsideMapTemplate(/** @type {JxPath | null} */ path) {
  * Field row with binding toggle — allows switching between static value and signal binding.
  * rawValue can be a string/bool (static) or { $ref: "..." } (bound).
  */
-/** @typedef {{ value: string; label: string }} SignalOption */
-
-/**
- * @typedef {{
- *   $section: string;
- *   $order: number;
- *   $elements?: string[];
- *   $label?: string;
- *   $input?: string;
- *   $shorthand?: boolean;
- *   type?: string;
- *   [key: string]: unknown;
- * }} HtmlMetaEntry
- */
-
 function bindableFieldRow(
-  /** @type {string} */ label,
-  /** @type {string} */ type,
-  /** @type {string | number | boolean | { $ref: string } | null | undefined} */ rawValue,
-  /** @type {(v: JsonValue) => void} */ onChange,
-  /** @type {((d: import("./signals-panel.js").SignalDef) => boolean) | null} */ filterFn = null,
-  /** @type {SignalOption[] | null} */ extraSignals = null,
+  label: string,
+  type: string,
+  rawValue: string | number | boolean | { $ref: string } | null | undefined,
+  onChange: (v: JsonValue) => void,
+  filterFn: ((d: import("./signals-panel.js").SignalDef) => boolean) | null = null,
+  extraSignals: SignalOption[] | null = null,
 ) {
   const tab = activeTab.value;
-  const defs = tab.doc.document.state || {};
+  const defs = tab!.doc.document.state || {};
   const isBound = typeof rawValue === "object" && rawValue !== null && rawValue.$ref;
 
   const signalDefs = Object.entries(defs).filter(([, d]) =>
-    filterFn ? filterFn(d) : !d.$handler && d.$prototype !== "Function",
+    filterFn
+      ? filterFn(d as import("./signals-panel.js").SignalDef)
+      : !(d as Record<string, unknown>)?.$handler &&
+        (d as JxPrototypeDef)?.$prototype !== "Function",
   );
 
   /** @type {ReturnType<typeof setTimeout> | undefined} */
-  let debounce;
-  const onInput = (/** @type {Event} */ e) => {
+  let debounce: ReturnType<typeof setTimeout> | undefined;
+  const onInput = (e: Event) => {
     clearTimeout(debounce);
-    debounce = setTimeout(() => onChange(/** @type {HTMLInputElement} */ (e.target).value), 400);
+    debounce = setTimeout(() => onChange((e.target as HTMLInputElement).value), 400);
   };
 
   const staticVal = isBound ? "" : (rawValue ?? "");
@@ -106,8 +115,7 @@ function bindableFieldRow(
       : type === "checkbox"
         ? html`<sp-checkbox
             ?checked=${!!staticVal}
-            @change=${(/** @type {Event} */ e) =>
-              onChange(/** @type {HTMLInputElement} */ (e.target).checked)}
+            @change=${(e: Event) => onChange((e.target as HTMLInputElement).checked)}
           ></sp-checkbox>`
         : html`<sp-textfield size="s" .value=${live(staticVal)} @input=${onInput}></sp-textfield>`;
 
@@ -117,9 +125,9 @@ function bindableFieldRow(
       quiet
       placeholder="— select signal —"
       value=${isBound && rawValue.$ref ? rawValue.$ref : nothing}
-      @change=${(/** @type {Event} */ e) => {
-        if (/** @type {HTMLInputElement} */ (e.target).value)
-          onChange({ $ref: /** @type {HTMLInputElement} */ (e.target).value });
+      @change=${(e: Event) => {
+        if ((e.target as HTMLInputElement).value)
+          onChange({ $ref: (e.target as HTMLInputElement).value });
         else onChange(undefined);
       }}
     >
@@ -130,7 +138,7 @@ function bindableFieldRow(
         ? html`
             <sp-menu-divider></sp-menu-divider>
             ${extraSignals.map(
-              (/** @type {SignalOption} */ sig) =>
+              (sig: SignalOption) =>
                 html`<sp-menu-item value=${sig.value}>${sig.label}</sp-menu-item>`,
             )}
           `
@@ -174,14 +182,14 @@ function bindableFieldRow(
 
 /** Key-value pair row for styles / attributes */
 function kvRow(
-  /** @type {string} */ key,
-  /** @type {string} */ value,
-  /** @type {(newKey: string, newVal: string) => void} */ onChange,
-  /** @type {() => void} */ onDelete,
+  key: string,
+  value: string,
+  onChange: (newKey: string, newVal: string) => void,
+  onDelete: () => void,
   /** @type {string | null} */ datalistId = null,
 ) {
   /** @type {ReturnType<typeof setTimeout> | undefined} */
-  let debounceTimer;
+  let debounceTimer: ReturnType<typeof setTimeout> | undefined;
   let currentKey = key;
   let currentVal = value;
   const commit = () => {
@@ -195,19 +203,19 @@ function kvRow(
         size="s"
         class="kv-key"
         .value=${live(key)}
-        @input=${(/** @type {Event} */ e) => {
-          currentKey = /** @type {HTMLInputElement} */ (e.target).value;
+        @input=${(e: Event) => {
+          currentKey = (e.target as HTMLInputElement).value;
           commit();
         }}
         @change=${datalistId === "css-props"
-          ? (/** @type {Event} */ e) => {
-              const el = /** @type {HTMLInputElement} */ (e.target)
+          ? (e: Event) => {
+              const el = (e.target as HTMLInputElement)
                 .closest(".kv-row")
                 ?.querySelector(".kv-val");
               if (el)
                 el.setAttribute(
                   "placeholder",
-                  getCssInitialMap().get(/** @type {HTMLInputElement} */ (e.target).value) || "",
+                  getCssInitialMap().get((e.target as HTMLInputElement).value) || "",
                 );
             }
           : nothing}
@@ -217,8 +225,8 @@ function kvRow(
         class="kv-val"
         .value=${live(value)}
         placeholder=${placeholder}
-        @input=${(/** @type {Event} */ e) => {
-          currentVal = /** @type {HTMLInputElement} */ (e.target).value;
+        @input=${(e: Event) => {
+          currentVal = (e.target as HTMLInputElement).value;
           commit();
         }}
       ></sp-textfield>
@@ -233,23 +241,23 @@ function kvRow(
 
 /** Repeater fields template */
 function renderRepeaterFieldsTemplate(
-  /** @type {JxMutableNode} */ node,
-  /** @type {JxPath} */ path,
-  /** @type {SignalOption[] | null} */ _mapSignals,
+  node: JxMutableNode,
+  path: JxPath,
+  _mapSignals: SignalOption[] | null,
 ) {
   return html`
-    ${bindableFieldRow("Items", "text", node.items, (/** @type {JsonValue} */ v) =>
+    ${bindableFieldRow("Items", "text", node.items, (v: JsonValue) =>
       transactDoc(activeTab.value, (t) => mutateUpdateProperty(t, path, "items", v)),
     )}
     ${node.filter
-      ? bindableFieldRow("Filter", "text", node.filter, (/** @type {JsonValue} */ v) =>
+      ? bindableFieldRow("Filter", "text", node.filter, (v: JsonValue) =>
           transactDoc(activeTab.value, (t) =>
             mutateUpdateProperty(t, path, "filter", v || undefined),
           ),
         )
       : nothing}
     ${node.sort
-      ? bindableFieldRow("Sort", "text", node.sort, (/** @type {JsonValue} */ v) =>
+      ? bindableFieldRow("Sort", "text", node.sort, (v: JsonValue) =>
           transactDoc(activeTab.value, (t) =>
             mutateUpdateProperty(t, path, "sort", v || undefined),
           ),
@@ -283,7 +291,7 @@ function renderRepeaterFieldsTemplate(
             size="s"
             style="margin-top:8px;width:100%"
             @click=${() => {
-              activeTab.value.session.selection = [...path, "map"];
+              activeTab.value!.session.selection = [...path, "map"];
             }}
             >Edit template →</sp-action-button
           >
@@ -294,9 +302,9 @@ function renderRepeaterFieldsTemplate(
 
 /** Switch fields template */
 function renderSwitchFieldsTemplate(
-  /** @type {JxMutableNode} */ node,
-  /** @type {JxPath} */ path,
-  /** @type {SignalOption[] | null} */ mapSignals,
+  node: JxMutableNode,
+  path: JxPath,
+  mapSignals: SignalOption[] | null,
 ) {
   const caseNames = Object.keys(node.cases || {});
   return html`
@@ -304,7 +312,7 @@ function renderSwitchFieldsTemplate(
       "Expression",
       "text",
       node.$switch,
-      (/** @type {JsonValue} */ v) =>
+      (v: JsonValue) =>
         transactDoc(activeTab.value, (t) => mutateUpdateProperty(t, path, "$switch", v)),
       null,
       mapSignals,
@@ -316,27 +324,22 @@ function renderSwitchFieldsTemplate(
     </div>
     ${caseNames.map((caseName) => {
       /** @type {ReturnType<typeof setTimeout> | undefined} */
-      let debounce;
+      let debounce: ReturnType<typeof setTimeout> | undefined;
       return html`
         <div class="field-row" style="display:flex;align-items:center;gap:4px;margin-bottom:3px">
           <input
             class="field-input"
             .value=${live(caseName)}
             style="flex:1"
-            @input=${(/** @type {Event} */ e) => {
+            @input=${(e: Event) => {
               clearTimeout(debounce);
               debounce = setTimeout(() => {
                 if (
-                  /** @type {HTMLInputElement} */ (e.target).value &&
-                  /** @type {HTMLInputElement} */ (e.target).value !== caseName
+                  (e.target as HTMLInputElement).value &&
+                  (e.target as HTMLInputElement).value !== caseName
                 )
                   transactDoc(activeTab.value, (t) =>
-                    mutateRenameSwitchCase(
-                      t,
-                      path,
-                      caseName,
-                      /** @type {HTMLInputElement} */ (e.target).value,
-                    ),
+                    mutateRenameSwitchCase(t, path, caseName, (e.target as HTMLInputElement).value),
                   );
               }, 500);
             }}
@@ -345,17 +348,17 @@ function renderSwitchFieldsTemplate(
             class="bind-toggle"
             title="Edit case"
             style="cursor:pointer"
-            @click=${(/** @type {Event} */ e) => {
+            @click=${(e: Event) => {
               e.stopPropagation();
-              activeTab.value.session.selection = [...path, "cases", caseName];
+              activeTab.value!.session.selection = [...path, "cases", caseName];
             }}
             >→</span
           >
           <span
             style="cursor:pointer;color:var(--danger);font-size:11px"
-            @click=${(/** @type {Event} */ e) => {
+            @click=${(e: Event) => {
               e.stopPropagation();
-              transactDoc(activeTab.value, (t) => mutateRemoveSwitchCase(t, path, caseName));
+              transactDoc(activeTab.value!, (t) => mutateRemoveSwitchCase(t, path, caseName));
             }}
             >✕</span
           >
@@ -376,10 +379,10 @@ function renderSwitchFieldsTemplate(
 
 /** Component props fields template */
 function renderComponentPropsFieldsTemplate(
-  /** @type {JxMutableNode} */ node,
-  /** @type {JxPath} */ path,
-  /** @type {SignalOption[] | null} */ mapSignals,
-  /** @type {(path: string) => void} */ navigateToComponent,
+  node: JxMutableNode,
+  path: JxPath,
+  mapSignals: SignalOption[] | null,
+  navigateToComponent: (path: string) => void,
 ) {
   const tab = activeTab.value;
   const comp = componentRegistry.find((c) => c.tagName === node.tagName);
@@ -387,21 +390,17 @@ function renderComponentPropsFieldsTemplate(
   const isNpm = comp.source === "npm";
   const currentVals = isNpm ? node.attributes || {} : node.$props || {};
   const updateFn = isNpm
-    ? (/** @type {string} */ name, /** @type {JsonValue} */ v) =>
+    ? (name: string, v: JsonValue) =>
         transactDoc(activeTab.value, (t) =>
-          mutateUpdateAttribute(
-            t,
-            path,
-            name,
-            v === "" ? undefined : /** @type {string | undefined} */ (v),
-          ),
+          mutateUpdateAttribute(t, path, name, v === "" ? undefined : (v as string | undefined)),
         )
-    : (/** @type {string} */ name, /** @type {JsonValue} */ v) =>
+    : (name: string, v: JsonValue) =>
         transactDoc(activeTab.value, (t) => mutateUpdateProp(t, path, name, v));
 
-  const defs = tab.doc.document.state || {};
+  const defs = tab!.doc.document.state || {};
   const signalDefs = Object.entries(defs).filter(
-    ([, d]) => !d.$handler && d.$prototype !== "Function",
+    ([, d]) =>
+      !(d as Record<string, unknown>)?.$handler && (d as JxPrototypeDef)?.$prototype !== "Function",
   );
   const extraSignals = mapSignals;
 
@@ -414,9 +413,10 @@ function renderComponentPropsFieldsTemplate(
         const isBound = typeof rawValue === "object" && rawValue !== null && rawValue.$ref;
         const hasVal = rawValue !== undefined && rawValue !== null;
         const parsed = parseCemType(prop.type);
-        const onChange = (/** @type {JsonValue} */ v) => updateFn(prop.name, v);
+        const onChange = (v: JsonValue) => updateFn(prop.name, v);
+        const staticVal = isBound ? "" : String(rawValue ?? "");
 
-        const clearProp = (/** @type {Event} */ e) => {
+        const clearProp = (e: Event) => {
           e.stopPropagation();
           updateFn(prop.name, undefined);
         };
@@ -446,9 +446,9 @@ function renderComponentPropsFieldsTemplate(
             quiet
             placeholder="— select signal —"
             value=${isBound && rawValue.$ref ? rawValue.$ref : nothing}
-            @change=${(/** @type {Event} */ e) => {
-              if (/** @type {HTMLInputElement} */ (e.target).value)
-                onChange({ $ref: /** @type {HTMLInputElement} */ (e.target).value });
+            @change=${(e: Event) => {
+              if ((e.target as HTMLInputElement).value)
+                onChange({ $ref: (e.target as HTMLInputElement).value });
               else onChange(undefined);
             }}
           >
@@ -460,7 +460,7 @@ function renderComponentPropsFieldsTemplate(
               ? html`
                   <sp-menu-divider></sp-menu-divider>
                   ${extraSignals.map(
-                    (/** @type {SignalOption} */ sig) =>
+                    (sig: SignalOption) =>
                       html`<sp-menu-item value=${sig.value}>${sig.label}</sp-menu-item>`,
                   )}
                 `
@@ -469,9 +469,7 @@ function renderComponentPropsFieldsTemplate(
         `;
 
         /** @type {ReturnType<typeof setTimeout> | undefined} */
-        let debounce;
-        const staticVal = isBound ? "" : (rawValue ?? "");
-        /** @type {import("lit-html").TemplateResult | undefined} */
+        let debounce: ReturnType<typeof setTimeout> | undefined;
         let widgetTpl;
         if (prop.format === "image") {
           widgetTpl = renderMediaPicker(prop.name, staticVal, onChange);
@@ -482,55 +480,43 @@ function renderComponentPropsFieldsTemplate(
             size="s"
             placeholder="YYYY-MM-DD"
             .value=${live(staticVal)}
-            @input=${(/** @type {Event} */ e) => {
+            @input=${(e: Event) => {
               clearTimeout(debounce);
-              debounce = setTimeout(
-                () => onChange(/** @type {HTMLInputElement} */ (e.target).value),
-                400,
-              );
+              debounce = setTimeout(() => onChange((e.target as HTMLInputElement).value), 400);
             }}
           ></sp-textfield>`;
         } else if (parsed.kind === "boolean") {
           widgetTpl = html`<sp-checkbox
             size="s"
             .checked=${live(!!staticVal)}
-            @change=${(/** @type {Event} */ e) =>
-              onChange(/** @type {HTMLInputElement} */ (e.target).checked || undefined)}
+            @change=${(e: Event) => onChange((e.target as HTMLInputElement).checked || undefined)}
           ></sp-checkbox>`;
         } else if (parsed.kind === "number") {
           widgetTpl = html`<sp-number-field
             size="s"
             .value=${live(staticVal)}
-            @input=${(/** @type {Event} */ e) => {
+            @input=${(e: Event) => {
               clearTimeout(debounce);
-              debounce = setTimeout(
-                () => onChange(/** @type {HTMLInputElement} */ (e.target).value),
-                400,
-              );
+              debounce = setTimeout(() => onChange((e.target as HTMLInputElement).value), 400);
             }}
           ></sp-number-field>`;
         } else if (parsed.kind === "combobox") {
-          const options = /** @type {string[]} */ (
-            /** @type {{ options?: string[] }} */ (parsed).options
-          );
+          const options = /** @type {{ options?: string[] }} */ (parsed).options as string[];
           widgetTpl = html`<jx-value-selector
             .value=${String(staticVal)}
             size="s"
             placeholder="—"
             .options=${options.map((o) => ({ value: o, label: camelToLabel(o) }))}
-            @change=${(/** @type {Event & { detail?: { value?: string } }} */ e) =>
-              onChange(e.detail?.value ?? /** @type {HTMLInputElement} */ (e.target).value)}
+            @change=${(e: Event & { detail?: { value?: string } }) =>
+              onChange(e.detail?.value ?? (e.target as HTMLInputElement).value)}
           ></jx-value-selector>`;
         } else {
           widgetTpl = html`<sp-textfield
             size="s"
             .value=${live(staticVal)}
-            @input=${(/** @type {Event} */ e) => {
+            @input=${(e: Event) => {
               clearTimeout(debounce);
-              debounce = setTimeout(
-                () => onChange(/** @type {HTMLInputElement} */ (e.target).value),
-                400,
-              );
+              debounce = setTimeout(() => onChange((e.target as HTMLInputElement).value), 400);
             }}
           ></sp-textfield>`;
         }
@@ -568,10 +554,10 @@ function renderComponentPropsFieldsTemplate(
 
 /** Custom attrs fields template */
 function renderCustomAttrsFieldsTemplate(
-  /** @type {JxMutableNode} */ node,
-  /** @type {JxPath} */ path,
-  /** @type {Record<string, unknown>} */ attrs,
-  /** @type {Set<string>} */ knownAttrNames,
+  node: JxMutableNode,
+  path: JxPath,
+  attrs: Record<string, unknown>,
+  knownAttrNames: Set<string>,
 ) {
   const customAttrs = Object.entries(attrs).filter(([k]) => !knownAttrNames.has(k));
   return html`
@@ -579,7 +565,7 @@ function renderCustomAttrsFieldsTemplate(
       kvRow(
         attr,
         String(val),
-        (/** @type {string} */ newAttr, /** @type {string} */ newVal) => {
+        (newAttr: string, newVal: string) => {
           if (newAttr !== attr) {
             transactDoc(activeTab.value, (t) => {
               mutateUpdateAttribute(t, path, attr, undefined);
@@ -604,10 +590,10 @@ function renderCustomAttrsFieldsTemplate(
 // ─── Media breakpoints ──────────────────────────────────────────────────────
 
 /** Media breakpoint fields template */
-function renderMediaFieldsTemplate(/** @type {JxMutableNode} */ node) {
+function renderMediaFieldsTemplate(node: JxMutableNode) {
   const media = node.$media || {};
   /** @type {ReturnType<typeof setTimeout> | undefined} */
-  let baseDebounce;
+  let baseDebounce: ReturnType<typeof setTimeout> | undefined;
   const breakpoints = Object.entries(media).filter(([k]) => k !== "--");
 
   return html`
@@ -618,10 +604,10 @@ function renderMediaFieldsTemplate(/** @type {JxMutableNode} */ node) {
         style="width:70px;flex:none"
         placeholder="320px"
         .value=${live(media["--"] || "")}
-        @input=${(/** @type {Event} */ e) => {
+        @input=${(e: Event) => {
           clearTimeout(baseDebounce);
           baseDebounce = setTimeout(() => {
-            const val = /** @type {HTMLInputElement} */ (e.target).value.trim();
+            const val = (e.target as HTMLInputElement).value.trim();
             transactDoc(activeTab.value, (t) => mutateUpdateMedia(t, "--", val || undefined));
           }, 400);
         }}
@@ -642,7 +628,7 @@ function renderMediaFieldsTemplate(/** @type {JxMutableNode} */ node) {
       <span
         class="kv-add"
         style=${view.showAddBreakpointForm ? "display:none" : ""}
-        @click=${(/** @type {Event} */ _e) => {
+        @click=${(_e: Event) => {
           view.showAddBreakpointForm = true;
           renderOnly("rightPanel");
         }}
@@ -656,9 +642,9 @@ function renderMediaFieldsTemplate(/** @type {JxMutableNode} */ node) {
                   class="field-input"
                   placeholder="Name (e.g. Tablet)"
                   style="flex:1"
-                  @input=${(/** @type {Event} */ e) => {
+                  @input=${(e: Event) => {
                     view.addBreakpointPreview =
-                      friendlyNameToMedia(/** @type {HTMLInputElement} */ (e.target).value) || "";
+                      friendlyNameToMedia((e.target as HTMLInputElement).value) || "";
                     renderOnly("rightPanel");
                   }}
                 />
@@ -674,13 +660,11 @@ function renderMediaFieldsTemplate(/** @type {JxMutableNode} */ node) {
                 <button
                   class="kv-add"
                   style="padding:2px 10px;cursor:pointer"
-                  @click=${(/** @type {Event} */ e) => {
-                    const wrap = /** @type {HTMLElement} */ (e.target).closest(
-                      "div",
-                    )?.parentElement;
+                  @click=${(e: Event) => {
+                    const wrap = (e.target as HTMLElement).closest("div")?.parentElement;
                     const nameVal = wrap?.querySelector("input")?.value;
-                    const queryVal = /** @type {HTMLInputElement | null} */ (
-                      wrap?.querySelector(".add-bp-query")
+                    const queryVal = (
+                      wrap?.querySelector(".add-bp-query") as HTMLInputElement | null
                     )?.value?.trim();
                     const key = friendlyNameToMedia(nameVal || "");
                     if (key && queryVal) {
@@ -712,9 +696,9 @@ function renderMediaFieldsTemplate(/** @type {JxMutableNode} */ node) {
 }
 
 /** Single media breakpoint row template */
-function mediaBreakpointRowTemplate(/** @type {string} */ name, /** @type {string} */ query) {
+function mediaBreakpointRowTemplate(name: string, query: string) {
   /** @type {ReturnType<typeof setTimeout> | undefined} */
-  let debounceTimer;
+  let debounceTimer: ReturnType<typeof setTimeout> | undefined;
   let currentRawLabel = name;
   return html`
     <div style="margin-bottom:6px;padding:4px 0;border-bottom:1px solid var(--border)">
@@ -723,21 +707,17 @@ function mediaBreakpointRowTemplate(/** @type {string} */ name, /** @type {strin
           class="field-input"
           .value=${live(mediaDisplayName(name))}
           style="flex:1;font-weight:600;font-size:12px"
-          @input=${(/** @type {Event} */ e) => {
-            const newKey = friendlyNameToMedia(/** @type {HTMLInputElement} */ (e.target).value);
+          @input=${(e: Event) => {
+            const newKey = friendlyNameToMedia((e.target as HTMLInputElement).value);
             currentRawLabel = newKey || "";
-            const rawEl = /** @type {HTMLElement} */ (e.target).parentElement?.querySelector(
-              ".bp-raw-label",
-            );
+            const rawEl = (e.target as HTMLElement).parentElement?.querySelector(".bp-raw-label");
             if (rawEl) rawEl.textContent = currentRawLabel;
             clearTimeout(debounceTimer);
             debounceTimer = setTimeout(() => {
               if (newKey && newKey !== name) {
-                const queryEl = /** @type {HTMLInputElement | null} */ (
-                  /** @type {HTMLElement} */ (e.target)
-                    .closest("div[style]")
-                    ?.parentElement?.querySelector(".bp-query-input")
-                );
+                const queryEl = (e.target as HTMLElement)
+                  .closest("div[style]")
+                  ?.parentElement?.querySelector(".bp-query-input") as HTMLInputElement | null;
                 transactDoc(activeTab.value, (t) => {
                   mutateUpdateMedia(t, name, undefined);
                   mutateUpdateMedia(t, newKey, queryEl?.value || query);
@@ -762,12 +742,12 @@ function mediaBreakpointRowTemplate(/** @type {string} */ name, /** @type {strin
           class="field-input bp-query-input"
           .value=${live(query)}
           style="flex:1"
-          @input=${(/** @type {Event} */ e) => {
+          @input=${(e: Event) => {
             clearTimeout(debounceTimer);
             debounceTimer = setTimeout(
               () =>
                 transactDoc(activeTab.value, (t) =>
-                  mutateUpdateMedia(t, name, /** @type {HTMLInputElement} */ (e.target).value),
+                  mutateUpdateMedia(t, name, (e.target as HTMLInputElement).value),
                 ),
               400,
             );
@@ -781,18 +761,15 @@ function mediaBreakpointRowTemplate(/** @type {string} */ name, /** @type {strin
 // ─── Layout picker ──────────────────────────────────────────────────────────
 
 /** @type {{ name: string; path: string }[] | null} */
-let layoutEntries = null;
+let layoutEntries: { name: string; path: string }[] | null = null;
 
 async function loadLayoutEntries() {
   try {
     const platform = getPlatform();
     const listing = await platform.listDirectory("layouts");
     layoutEntries = listing
-      .filter(
-        (/** @type {{ type: string; name: string }} */ f) =>
-          f.type === "file" && f.name.endsWith(".json"),
-      )
-      .map((/** @type {{ type: string; name: string }} */ f) => ({
+      .filter((f: DirEntry) => f.type === "file" && f.name.endsWith(".json"))
+      .map((f: DirEntry) => ({
         name: f.name.replace(/\.json$/, ""),
         path: `./layouts/${f.name}`,
       }));
@@ -806,14 +783,14 @@ export function invalidateLayoutPickerCache() {
   layoutEntries = null;
 }
 
-function isPageDocument(/** @type {string | undefined | null} */ documentPath) {
+function isPageDocument(documentPath: string | undefined | null) {
   if (!documentPath || !projectState?.isSiteProject) return false;
   return documentPath.startsWith("pages/") || documentPath.startsWith("./pages/");
 }
 
-function renderPageSection(/** @type {JxMutableNode} */ node) {
+function renderPageSection(node: JxMutableNode) {
   const tab = activeTab.value;
-  if (!isPageDocument(tab.documentPath)) return nothing;
+  if (!isPageDocument(tab!.documentPath)) return nothing;
 
   if (layoutEntries === null) {
     loadLayoutEntries();
@@ -835,7 +812,7 @@ function renderPageSection(/** @type {JxMutableNode} */ node) {
               ? html`<span
                   class="set-dot"
                   title="Reset to default"
-                  @click=${(/** @type {Event} */ e) => {
+                  @click=${(e: Event) => {
                     e.stopPropagation();
                     transactDoc(activeTab.value, (t) =>
                       mutateUpdateProperty(t, [], "$layout", undefined),
@@ -848,8 +825,8 @@ function renderPageSection(/** @type {JxMutableNode} */ node) {
           <sp-picker
             size="s"
             value=${displayValue}
-            @change=${(/** @type {Event} */ e) => {
-              const val = /** @type {HTMLInputElement} */ (e.target).value;
+            @change=${(e: Event) => {
+              const val = (e.target as HTMLInputElement).value;
               if (val === "__default__") {
                 transactDoc(activeTab.value, (t) =>
                   mutateUpdateProperty(t, [], "$layout", undefined),
@@ -869,8 +846,8 @@ function renderPageSection(/** @type {JxMutableNode} */ node) {
             >
             <sp-menu-item value="__none__">None</sp-menu-item>
             <sp-menu-divider></sp-menu-divider>
-            ${layoutEntries.map(
-              (/** @type {{ name: string; path: string }} */ l) =>
+            ${layoutEntries!.map(
+              (l: { name: string; path: string }) =>
                 html`<sp-menu-item value=${l.path}>${l.name}</sp-menu-item>`,
             )}
           </sp-picker>
@@ -887,12 +864,8 @@ function renderPageSection(/** @type {JxMutableNode} */ node) {
 
 // ─── Layout selection panel ─────────────────────────────────────────────────
 
-function renderLayoutSelectionPanel(
-  /** @type {{ navigateToComponent: (path: string) => void }} */ ctx,
-) {
-  const { el, layoutPath } = /** @type {{ el: HTMLElement; layoutPath: string }} */ (
-    view.layoutSelection
-  );
+function renderLayoutSelectionPanel(ctx: { navigateToComponent: (path: string) => void }) {
+  const { el, layoutPath } = view.layoutSelection as { el: HTMLElement; layoutPath: string };
   const tagName = el?.tagName?.toLowerCase() || "element";
   const className = el?.className || "";
   const displayPath = layoutPath || "layout";
@@ -939,7 +912,9 @@ function renderLayoutSelectionPanel(
  *
  * @param {{ navigateToComponent: (path: string) => void }} ctx
  */
-export function renderPropertiesPanelTemplate(ctx) {
+export function renderPropertiesPanelTemplate(ctx: {
+  navigateToComponent: (path: string) => void;
+}) {
   const tab = activeTab.value;
   if (!tab) return html`<div class="empty-state">No document loaded</div>`;
 
@@ -959,7 +934,7 @@ export function renderPropertiesPanelTemplate(ctx) {
   const isMapParent =
     node.children &&
     typeof node.children === "object" &&
-    /** @type {{ $prototype?: string }} */ (node.children).$prototype === "Array";
+    (node.children as unknown as { $prototype?: string }).$prototype === "Array";
   const isSwitchNode = !!node.$switch;
   const isCustomInstance = (node.tagName || "").includes("-");
   const isRoot = path.length === 0;
@@ -973,11 +948,7 @@ export function renderPropertiesPanelTemplate(ctx) {
       ]
     : null;
 
-  function renderAttrRow(
-    /** @type {string} */ attr,
-    /** @type {HtmlMetaEntry} */ entry,
-    /** @type {unknown} */ value,
-  ) {
+  function renderAttrRow(attr: string, entry: HtmlMetaEntry, value: unknown) {
     const type = inferInputType(entry);
     const hasVal = value !== undefined && value !== "";
 
@@ -992,13 +963,13 @@ export function renderPropertiesPanelTemplate(ctx) {
           <sp-checkbox
             size="s"
             .checked=${live(!!value)}
-            @change=${(/** @type {Event} */ e) =>
+            @change=${(e: Event) =>
               transactDoc(activeTab.value, (t) =>
                 mutateUpdateAttribute(
                   t,
                   path,
                   attr,
-                  /** @type {HTMLInputElement} */ (e.target).checked ? "" : undefined,
+                  (e.target as HTMLInputElement).checked ? "" : undefined,
                 ),
               )}
           >
@@ -1013,23 +984,21 @@ export function renderPropertiesPanelTemplate(ctx) {
       hasValue: hasVal,
       onClear: () =>
         transactDoc(activeTab.value, (t) => mutateUpdateAttribute(t, path, attr, undefined)),
-      widget: widgetForType(type, entry, attr, String(value || ""), (/** @type {string} */ v) =>
-        transactDoc(activeTab.value, (t) => mutateUpdateAttribute(t, path, attr, v || undefined)),
+      widget: widgetForType(type, entry, attr, String(value || ""), (v: string) =>
+        transactDoc(activeTab.value!, (t) => mutateUpdateAttribute(t, path, attr, v || undefined)),
       ),
     });
   }
 
   // ── Collect applicable attributes from html-meta ──
-  const applicableAttrs = /** @type {Record<string, HtmlMetaEntry>} */ ({});
-  for (const [attr, entry] of /** @type {[string, HtmlMetaEntry][]} */ (
-    Object.entries(htmlMeta.$defs)
-  )) {
+  const applicableAttrs = {} as Record<string, HtmlMetaEntry>;
+  for (const [attr, entry] of Object.entries(htmlMeta.$defs) as [string, HtmlMetaEntry][]) {
     if (!entry.$elements || entry.$elements.includes(tagName)) {
       applicableAttrs[attr] = entry;
     }
   }
 
-  const attrSections = /** @type {Record<string, { name: string; entry: HtmlMetaEntry }[]>} */ ({});
+  const attrSections: Record<string, { name: string; entry: HtmlMetaEntry }[]> = {};
   for (const sec of htmlMeta.$sections) attrSections[sec.key] = [];
   for (const [attr, entry] of Object.entries(applicableAttrs)) {
     const secKey = entry.$section;
@@ -1037,10 +1006,8 @@ export function renderPropertiesPanelTemplate(ctx) {
   }
   for (const sec of htmlMeta.$sections) {
     attrSections[sec.key].sort(
-      (
-        /** @type {{ name: string; entry: HtmlMetaEntry }} */ a,
-        /** @type {{ name: string; entry: HtmlMetaEntry }} */ b,
-      ) => a.entry.$order - b.entry.$order,
+      (a: { name: string; entry: HtmlMetaEntry }, b: { name: string; entry: HtmlMetaEntry }) =>
+        a.entry.$order - b.entry.$order,
     );
   }
 
@@ -1058,16 +1025,16 @@ export function renderPropertiesPanelTemplate(ctx) {
   }
   if (customAttrs.length > 0) autoOpen.add("__custom");
 
-  function isSectionOpen(/** @type {string} */ key) {
-    if (tab.session.ui.inspectorSections[key] !== undefined)
-      return tab.session.ui.inspectorSections[key];
+  function isSectionOpen(key: string) {
+    if (tab!.session.ui.inspectorSections[key] !== undefined)
+      return tab!.session.ui.inspectorSections[key];
     return autoOpen.has(key);
   }
 
-  function toggleSection(/** @type {string} */ key) {
+  function toggleSection(key: string) {
     const current = isSectionOpen(key);
-    activeTab.value.session.ui.inspectorSections = {
-      ...activeTab.value.session.ui.inspectorSections,
+    activeTab.value!.session.ui.inspectorSections = {
+      ...activeTab.value!.session.ui.inspectorSections,
       [key]: !current,
     };
   }
@@ -1090,13 +1057,13 @@ export function renderPropertiesPanelTemplate(ctx) {
             .value=${live(tagName)}
             autocomplete="off"
             list="tag-names"
-            @input=${debouncedStyleCommit("prop:tagName", 400, (/** @type {Event} */ e) => {
+            @input=${debouncedStyleCommit("prop:tagName", 400, (e: Event) => {
               transactDoc(activeTab.value, (t) =>
                 mutateUpdateProperty(
                   t,
                   path,
                   "tagName",
-                  /** @type {HTMLInputElement} */ (e.target).value || undefined,
+                  (e.target as HTMLInputElement).value || undefined,
                 ),
               );
             })}
@@ -1108,7 +1075,7 @@ export function renderPropertiesPanelTemplate(ctx) {
               ? html`<span
                   class="set-dot"
                   title="Clear $id"
-                  @click=${(/** @type {Event} */ e) => {
+                  @click=${(e: Event) => {
                     e.stopPropagation();
                     transactDoc(activeTab.value, (t) =>
                       mutateUpdateProperty(t, path, "$id", undefined),
@@ -1121,13 +1088,13 @@ export function renderPropertiesPanelTemplate(ctx) {
           <sp-textfield
             size="s"
             .value=${live(node.$id || "")}
-            @input=${debouncedStyleCommit("prop:$id", 400, (/** @type {Event} */ e) => {
+            @input=${debouncedStyleCommit("prop:$id", 400, (e: Event) => {
               transactDoc(activeTab.value, (t) =>
                 mutateUpdateProperty(
                   t,
                   path,
                   "$id",
-                  /** @type {HTMLInputElement} */ (e.target).value || undefined,
+                  (e.target as HTMLInputElement).value || undefined,
                 ),
               );
             })}
@@ -1139,7 +1106,7 @@ export function renderPropertiesPanelTemplate(ctx) {
               ? html`<span
                   class="set-dot"
                   title="Clear class"
-                  @click=${(/** @type {Event} */ e) => {
+                  @click=${(e: Event) => {
                     e.stopPropagation();
                     transactDoc(activeTab.value, (t) =>
                       mutateUpdateProperty(t, path, "className", undefined),
@@ -1152,13 +1119,13 @@ export function renderPropertiesPanelTemplate(ctx) {
           <sp-textfield
             size="s"
             .value=${live(node.className || "")}
-            @input=${debouncedStyleCommit("prop:className", 400, (/** @type {Event} */ e) => {
+            @input=${debouncedStyleCommit("prop:className", 400, (e: Event) => {
               transactDoc(activeTab.value, (t) =>
                 mutateUpdateProperty(
                   t,
                   path,
                   "className",
-                  /** @type {HTMLInputElement} */ (e.target).value || undefined,
+                  (e.target as HTMLInputElement).value || undefined,
                 ),
               );
             })}
@@ -1172,7 +1139,7 @@ export function renderPropertiesPanelTemplate(ctx) {
                     ? html`<span
                         class="set-dot"
                         title="Clear text"
-                        @click=${(/** @type {Event} */ e) => {
+                        @click=${(e: Event) => {
                           e.stopPropagation();
                           transactDoc(activeTab.value, (t) =>
                             mutateUpdateProperty(t, path, "textContent", undefined),
@@ -1190,20 +1157,16 @@ export function renderPropertiesPanelTemplate(ctx) {
                       ? node.textContent
                       : (node.textContent ?? ""),
                   )}
-                  @input=${debouncedStyleCommit(
-                    "prop:textContent",
-                    400,
-                    (/** @type {Event} */ e) => {
-                      transactDoc(activeTab.value, (t) =>
-                        mutateUpdateProperty(
-                          t,
-                          path,
-                          "textContent",
-                          /** @type {HTMLInputElement} */ (e.target).value || undefined,
-                        ),
-                      );
-                    },
-                  )}
+                  @input=${debouncedStyleCommit("prop:textContent", 400, (e: Event) => {
+                    transactDoc(activeTab.value, (t) =>
+                      mutateUpdateProperty(
+                        t,
+                        path,
+                        "textContent",
+                        (e.target as HTMLInputElement).value || undefined,
+                      ),
+                    );
+                  })}
                 ></sp-textfield>
               </div>
             `
@@ -1214,7 +1177,7 @@ export function renderPropertiesPanelTemplate(ctx) {
               ? html`<span
                   class="set-dot"
                   title="Clear hidden"
-                  @click=${(/** @type {Event} */ e) => {
+                  @click=${(e: Event) => {
                     e.stopPropagation();
                     transactDoc(activeTab.value, (t) =>
                       mutateUpdateProperty(t, path, "hidden", undefined),
@@ -1227,13 +1190,13 @@ export function renderPropertiesPanelTemplate(ctx) {
           <sp-checkbox
             size="s"
             .checked=${live(!!node.hidden)}
-            @change=${(/** @type {Event} */ e) =>
+            @change=${(e: Event) =>
               transactDoc(activeTab.value, (t) =>
                 mutateUpdateProperty(
                   t,
                   path,
                   "hidden",
-                  /** @type {HTMLInputElement} */ (e.target).checked || undefined,
+                  (e.target as HTMLInputElement).checked || undefined,
                 ),
               )}
           >
@@ -1274,7 +1237,9 @@ export function renderPropertiesPanelTemplate(ctx) {
     isCustomElementDoc({ document: tab.doc.document }) && isRoot
       ? (() => {
           const state = tab.doc.document.state || {};
-          const entries = Object.entries(state).filter(([, d]) => d.attribute);
+          const entries = Object.entries(state).filter(
+            ([, d]) => (d as Record<string, unknown>).attribute,
+          );
           return html`
             <sp-accordion-item label="Observed Attributes" ?open=${isSectionOpen("__observed")}>
               <div class="style-section-body">
@@ -1282,30 +1247,31 @@ export function renderPropertiesPanelTemplate(ctx) {
                   ? html`<div class="empty-state">
                       No attributes declared. Set "attribute" on a state entry.
                     </div>`
-                  : entries.map(
-                      ([key, d]) => html`
+                  : entries.map(([key, d]) => {
+                      const def = d as Record<string, unknown>;
+                      return html`
                         <div
                           style="display:flex;gap:6px;align-items:center;padding:2px 0;font-size:11px"
                         >
                           <code style="font-family:monospace;color:var(--accent)"
-                            >${d.attribute}</code
+                            >${def.attribute}</code
                           >
                           <span style="color:var(--fg-dim)"> → </span>
                           <span>${key}</span>
-                          ${d.type
+                          ${def.type
                             ? html`<span style="margin-left:auto;color:var(--fg-dim);font-size:10px"
-                                >${d.type}</span
+                                >${def.type}</span
                               >`
                             : nothing}
-                          ${d.reflects
+                          ${def.reflects
                             ? html`<span
                                 style="font-size:9px;background:var(--bg-hover);padding:1px 4px;border-radius:3px"
                                 >reflects</span
                               >`
                             : nothing}
                         </div>
-                      `,
-                    )}
+                      `;
+                    })}
               </div>
             </sp-accordion-item>
           `;
@@ -1327,7 +1293,7 @@ export function renderPropertiesPanelTemplate(ctx) {
     .map((sec) => {
       const sectionAttrs = attrSections[sec.key];
       const hasAnySet = sectionAttrs.some(
-        (/** @type {{ name: string; entry: HtmlMetaEntry }} */ a) => attrs[a.name] !== undefined,
+        (a: { name: string; entry: HtmlMetaEntry }) => attrs[a.name] !== undefined,
       );
       return html`
         <sp-accordion-item
@@ -1339,7 +1305,7 @@ export function renderPropertiesPanelTemplate(ctx) {
             ? html`<span slot="heading" class="set-dot set-dot--section"></span>`
             : nothing}
           <div class="style-section-body">
-            ${sectionAttrs.map((/** @type {{ name: string; entry: HtmlMetaEntry }} */ a) =>
+            ${sectionAttrs.map((a: { name: string; entry: HtmlMetaEntry }) =>
               renderAttrRow(a.name, a.entry, attrs[a.name]),
             )}
           </div>