From 62067e2258b539742eedfb9270ce6de78fa755eb Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 2 Jul 2026 06:40:11 +0000
Subject: [PATCH 1/2] refactor(configurator): type codec.ts and its call sites,
 document shared limit constants

SL-017/024: replace `any` at codec.ts's 7 registry/options parameters and
its two consumers (App.svelte, CheatsheetPanel.svelte) with new TokenRegistry,
ApiIndex, SlashedClass and DecodeOptions interfaces in types.ts, so malformed
JSON or option shapes are caught at compile time instead of silently
no-op'ing at runtime.

SL-026: document why MAX_VALUE_BYTES and MAX_ID share the same numeric
value (65535) despite being independent limits, so a future edit doesn't
assume they're the same constant in disguise.
---
 configurator/src/App.svelte                   |  4 +-
 .../components/panels/CheatsheetPanel.svelte  |  7 +--
 configurator/src/lib/codec.ts                 | 20 ++++---
 configurator/src/types.ts                     | 54 +++++++++++++++++++
 4 files changed, 73 insertions(+), 12 deletions(-)

diff --git a/configurator/src/App.svelte b/configurator/src/App.svelte
index fb436fa0..937b0704 100644
--- a/configurator/src/App.svelte
+++ b/configurator/src/App.svelte
@@ -1,7 +1,7 @@
 <script lang="ts">
   import { onMount, untrack } from 'svelte';
   import { SlidersHorizontal, Eye, RotateCcw } from 'lucide-svelte';
-  import type { PreviewTemplate, SlashedToken } from './types';
+  import type { PreviewTemplate, SlashedToken, ApiIndex } from './types';
   import StudioHeader from './components/shell/StudioHeader.svelte';
   import SidebarNav from './components/shell/SidebarNav.svelte';
   import StatusBar from './components/shell/StatusBar.svelte';
@@ -13,7 +13,7 @@
   import tokensRaw from './data/api-index.generated.json';
   import CommandPalette from './components/CommandPalette.svelte';
 
-  const ALL_TOKENS = ((tokensRaw as any).tokens ?? tokensRaw) as SlashedToken[];
+  const ALL_TOKENS = ((tokensRaw as ApiIndex).tokens ?? tokensRaw) as SlashedToken[];
 
   const DOMAIN_LABELS: Record<string, string> = {
     home: "Home", colors: "Colors", typography: "Typography", spacing: "Spacing",
diff --git a/configurator/src/components/panels/CheatsheetPanel.svelte b/configurator/src/components/panels/CheatsheetPanel.svelte
index 3b83f4c1..1fe7edbc 100644
--- a/configurator/src/components/panels/CheatsheetPanel.svelte
+++ b/configurator/src/components/panels/CheatsheetPanel.svelte
@@ -6,9 +6,10 @@
   import classesData from '../../data/classes.generated.json';
   import tokensData from '../../data/api-index.generated.json';
   import { Copy, Check } from 'lucide-svelte';
+  import type { SlashedClass } from '../../types';
 
   const classes = classesData.classes;
-  const tokens = tokensData.tokens.filter((t: any) => t.tier === 'PUBLIC' || t.tier === 'PUBLIC-ADVANCED');
+  const tokens = tokensData.tokens.filter((t) => t.tier === 'PUBLIC' || t.tier === 'PUBLIC-ADVANCED');
 
   let query = $state('');
   let tab = $state<'classes' | 'tokens'>('classes');
@@ -17,7 +18,7 @@
   let filteredClasses = $derived(() => {
     const q = query.trim().toLowerCase();
     if (!q) return classes;
-    return classes.filter((c: any) =>
+    return classes.filter((c: SlashedClass) =>
       c.name.toLowerCase().includes(q) ||
       c.selector?.toLowerCase().includes(q) ||
       c.description?.toLowerCase().includes(q) ||
@@ -28,7 +29,7 @@
   let filteredTokens = $derived(() => {
     const q = query.trim().toLowerCase();
     if (!q) return tokens;
-    return tokens.filter((t: any) =>
+    return tokens.filter((t) =>
       t.name.toLowerCase().includes(q) ||
       t.description?.toLowerCase().includes(q) ||
       t.group?.toLowerCase().includes(q) ||
diff --git a/configurator/src/lib/codec.ts b/configurator/src/lib/codec.ts
index f18f048f..75118271 100644
--- a/configurator/src/lib/codec.ts
+++ b/configurator/src/lib/codec.ts
@@ -5,6 +5,7 @@
 
 import { deflateSync, inflateSync } from "fflate";
 import tokensData from "../data/token-registry.generated.json";
+import type { TokenRegistry, DecodeOptions } from "../types";
 
 declare const __SLASHED_VERSION__: string;
 
@@ -13,6 +14,11 @@ const frameworkVersion: string = typeof __SLASHED_VERSION__ !== "undefined" ? __
 export const CODEC_VERSION = 2;
 export const SHARE_PARAM = "c";
 
+// SL-026: MAX_VALUE_BYTES and MAX_ID happen to share the same value (both
+// bounded by the 2-byte length-prefix / id field in the wire format — see
+// encode()'s payload layout below) but are independent limits for unrelated
+// things (a value's encoded byte length vs. a token's registry id). Don't
+// assume changing one should change the other.
 const MAX_VALUE_BYTES = 65535;
 const MAX_ID = 65535;
 const textEncoder = new TextEncoder();
@@ -24,7 +30,7 @@ function isValidId(id: number): boolean {
   return Number.isInteger(id) && id >= 0 && id <= MAX_ID;
 }
 
-function buildNameToIdMap(registry: any): Map<string, number> {
+function buildNameToIdMap(registry: TokenRegistry): Map<string, number> {
   const nameToId = new Map<string, number>();
   for (const entry of registry?.tokens ?? []) {
     if (entry && !entry.removed && typeof entry.name === "string" && isValidId(entry.id)) {
@@ -34,7 +40,7 @@ function buildNameToIdMap(registry: any): Map<string, number> {
   return nameToId;
 }
 
-function buildIdToNameMap(registry: any): Map<number, string> {
+function buildIdToNameMap(registry: TokenRegistry): Map<number, string> {
   const idToName = new Map<number, string>();
   for (const entry of registry?.tokens ?? []) {
     if (entry && typeof entry.name === "string" && Number.isInteger(entry.id)) {
@@ -72,7 +78,7 @@ function base64UrlToBytes(value: string): Uint8Array | null {
   }
 }
 
-export function encode(overrides: Record<string, string>, registry: any = tokensData): string {
+export function encode(overrides: Record<string, string>, registry: TokenRegistry = tokensData): string {
   if (!overrides || typeof overrides !== "object") return "";
   const nameToId = buildNameToIdMap(registry);
   const entries: { id: number; valueBytes: Uint8Array }[] = [];
@@ -114,7 +120,7 @@ export function encode(overrides: Record<string, string>, registry: any = tokens
   return bytesToBase64Url(out);
 }
 
-export function decode(code: string, registry: any = tokensData, options: any = {}): Record<string, string> {
+export function decode(code: string, registry: TokenRegistry = tokensData, options: DecodeOptions = {}): Record<string, string> {
   const trimmed = String(code ?? "").trim();
   if (trimmed === "") return {};
   const rawBytes = base64UrlToBytes(trimmed);
@@ -258,8 +264,8 @@ export function encodeOverrides(overrides: Record<string, string>): string {
 
 const SHARE_PARAM_RE = new RegExp(`[#&]?${SHARE_PARAM}=([^&]+)`);
 
-export function readShareFromHash(hashOrParam: string, options: any = {}): Record<string, string> {
-  const knownTokensSet = new Set(tokensData.tokens.map((tok: any) => tok.name));
+export function readShareFromHash(hashOrParam: string, options: DecodeOptions = {}): Record<string, string> {
+  const knownTokensSet = new Set(tokensData.tokens.map((tok) => tok.name));
   const isKnown = options.isKnown ?? ((name: string) => knownTokensSet.has(name));
   let trimmed = String(hashOrParam ?? "").trim();
   const match = trimmed.match(SHARE_PARAM_RE);
@@ -278,7 +284,7 @@ export function buildShareUrl(overrides: Record<string, string>, baseUrlOverride
   return url.toString();
 }
 
-export function readShareFromHashIfPresent(hash: string, options: any = {}): Record<string, string> {
+export function readShareFromHashIfPresent(hash: string, options: DecodeOptions = {}): Record<string, string> {
   const value = String(hash ?? "");
   return value.includes(`${SHARE_PARAM}=`) ? readShareFromHash(value, options) : {};
 }
diff --git a/configurator/src/types.ts b/configurator/src/types.ts
index 7d18d08c..e82f857f 100644
--- a/configurator/src/types.ts
+++ b/configurator/src/types.ts
@@ -19,6 +19,60 @@ export interface SlashedToken {
   syntax?: string | null;
 }
 
+// SL-017/024: types for the two consumed-generated-JSON shapes and codec.ts's
+// options objects, replacing `any` at their 7 call sites.
+
+/** A token entry as it appears in data/api-index.generated.json's `tokens` array. */
+export interface ApiIndexToken extends SlashedToken {
+  fallbackOnly?: boolean;
+  optional?: boolean;
+  layer?: string | null;
+  bundles?: string[];
+}
+
+/** Shape of data/api-index.generated.json (configurator/scripts/sync-api.mjs's output). */
+export interface ApiIndex {
+  _sync?: Record<string, unknown>;
+  tokens: ApiIndexToken[];
+}
+
+/** A class entry as it appears in data/classes.generated.json's `classes` array. */
+export interface SlashedClass {
+  name: string;
+  selector: string;
+  kind: string;
+  category: string;
+  group?: string;
+  description?: string;
+  optional?: boolean;
+  layer?: string | null;
+}
+
+/** Shape of data/classes.generated.json (configurator/scripts/sync-api.mjs's output). */
+export interface ClassIndex {
+  _sync?: Record<string, unknown>;
+  classes: SlashedClass[];
+}
+
+/** A registry entry as it appears in data/token-registry.generated.json's `tokens` array. */
+export interface TokenRegistryEntry {
+  id: number;
+  name: string;
+  removed?: boolean;
+}
+
+/** Shape of data/token-registry.generated.json, consumed by codec.ts's encode/decode. */
+export interface TokenRegistry {
+  _meta?: Record<string, unknown>;
+  tokens: TokenRegistryEntry[];
+}
+
+/** Options accepted by codec.ts's decode() / readShareFromHash() / readShareFromHashIfPresent(). */
+export interface DecodeOptions {
+  sanitize?: (value: string) => string;
+  isKnown?: (tokenName: string) => boolean;
+}
+
 export interface SlashedCategory {
   id: string;
   label: string;

From 2af608fcb23b93630e8e172bb16de3abd150eda8 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 2 Jul 2026 06:47:01 +0000
Subject: [PATCH 2/2] fix(configurator): stop advertising an ignored sanitize
 option on share-link readers

readShareFromHash()/readShareFromHashIfPresent() were typed to accept
DecodeOptions.sanitize but always forced sanitizeValue internally (a
CSS-injection safeguard that must not be caller-overridable) and silently
discarded any options.sanitize passed in. Narrow their accepted options to
a new ShareOptions type (isKnown only) so the signature matches actual
behavior instead of advertising a knob that does nothing.
---
 configurator/src/lib/codec.ts |  6 +++---
 configurator/src/types.ts     | 10 +++++++++-
 2 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/configurator/src/lib/codec.ts b/configurator/src/lib/codec.ts
index 75118271..7b08c06e 100644
--- a/configurator/src/lib/codec.ts
+++ b/configurator/src/lib/codec.ts
@@ -5,7 +5,7 @@
 
 import { deflateSync, inflateSync } from "fflate";
 import tokensData from "../data/token-registry.generated.json";
-import type { TokenRegistry, DecodeOptions } from "../types";
+import type { TokenRegistry, DecodeOptions, ShareOptions } from "../types";
 
 declare const __SLASHED_VERSION__: string;
 
@@ -264,7 +264,7 @@ export function encodeOverrides(overrides: Record<string, string>): string {
 
 const SHARE_PARAM_RE = new RegExp(`[#&]?${SHARE_PARAM}=([^&]+)`);
 
-export function readShareFromHash(hashOrParam: string, options: DecodeOptions = {}): Record<string, string> {
+export function readShareFromHash(hashOrParam: string, options: ShareOptions = {}): Record<string, string> {
   const knownTokensSet = new Set(tokensData.tokens.map((tok) => tok.name));
   const isKnown = options.isKnown ?? ((name: string) => knownTokensSet.has(name));
   let trimmed = String(hashOrParam ?? "").trim();
@@ -284,7 +284,7 @@ export function buildShareUrl(overrides: Record<string, string>, baseUrlOverride
   return url.toString();
 }
 
-export function readShareFromHashIfPresent(hash: string, options: DecodeOptions = {}): Record<string, string> {
+export function readShareFromHashIfPresent(hash: string, options: ShareOptions = {}): Record<string, string> {
   const value = String(hash ?? "");
   return value.includes(`${SHARE_PARAM}=`) ? readShareFromHash(value, options) : {};
 }
diff --git a/configurator/src/types.ts b/configurator/src/types.ts
index e82f857f..8f576474 100644
--- a/configurator/src/types.ts
+++ b/configurator/src/types.ts
@@ -67,12 +67,20 @@ export interface TokenRegistry {
   tokens: TokenRegistryEntry[];
 }
 
-/** Options accepted by codec.ts's decode() / readShareFromHash() / readShareFromHashIfPresent(). */
+/** Options accepted by codec.ts's decode(). */
 export interface DecodeOptions {
   sanitize?: (value: string) => string;
   isKnown?: (tokenName: string) => boolean;
 }
 
+/**
+ * Options accepted by codec.ts's readShareFromHash() / readShareFromHashIfPresent().
+ * Deliberately omits `sanitize` (unlike DecodeOptions): these are the public
+ * share-link entry points and always force sanitizeValue as a CSS-injection
+ * safeguard, so a caller-supplied sanitize is never honoured.
+ */
+export type ShareOptions = Pick<DecodeOptions, "isKnown">;
+
 export interface SlashedCategory {
   id: string;
   label: string;