@ikas/bp-storefront 1.4.0-beta.88 → 1.4.0-beta.89

package/dist/storefront-config/src/theme-globals.d.ts

@@ -118,25 +118,35 @@ export type ThemeGlobals = {
     };
 };
 /**
- * Runtime-facing token views returned by the `@ikas/bp-storefront` getters
- * (`getThemeColors` / `getThemeTypography` / ...). They intentionally OMIT `name`: at runtime
- * a token must be identified by its STABLE `id` (color → `cssVar` / `var(--<id>)`, typography
- * & keyframe → `className`/`ref` `_<id>`, color-scheme slot → a `colorsByScheme` key), NEVER by
- * its human name. Names are non-unique (two design assets can ship the same name) and renaming
- * them must not break references, so reading `.name` at render is an anti-pattern — hiding it
- * from the return type turns that into a compile error.
+ * Stamps a theme-token type as its RUNTIME view returned by the `@ikas/bp-storefront` getters
+ * (`getThemeColors` / `getThemeTypography` / ...). `name` is removed, then re-added as a
+ * DEPRECATED `never`. Plainly `Omit`-ing it would only ever surface a bare "Property 'name' does
+ * not exist on type" — re-adding it as a documented `@deprecated never` instead means a developer
+ * who reaches for `.name` at runtime sees the strikethrough + the explanation below on hover, and
+ * any actual use of the value is a type error (`never`). The agent is steered the same way.
  *
- * The full types above (with `name`) are still produced in the serialized {@link ThemeGlobals}
- * payload and surfaced by the CLI/MCP `list-theme-globals` AUTHORING read, so the agent/editor
- * can still discover and reuse existing tokens by name. `name` is hidden ONLY from the runtime
- * getter return types.
+ * The full types above (with a real `name: string`) are still produced in the serialized
+ * {@link ThemeGlobals} payload and surfaced by the CLI/MCP `list-theme-globals` AUTHORING read, so
+ * the agent/editor can still discover and reuse existing tokens by name. `name` is hidden ONLY at
+ * the runtime getter return types (the getters cast the live payload to these views).
  */
-export type RuntimeDesignToken = Omit<DesignToken, "name">;
-export type RuntimeTypographyToken = Omit<TypographyToken, "name">;
-export type RuntimeBreakpointToken = Omit<BreakpointToken, "name">;
-export type RuntimeKeyframeToken = Omit<KeyframeToken, "name">;
-export type RuntimeColorSchemeToken = Omit<ColorSchemeToken, "name">;
-export type RuntimeColorSchemeSlot = Omit<ColorSchemeSlot, "name">;
+type RuntimeView<T> = Omit<T, "name"> & {
+    /**
+     * @deprecated `name` is authoring-only and is NOT exposed at runtime. Identify this token by its
+     * STABLE `id` instead — color → `cssVar` (`var(--<id>)`), typography & keyframe → `className` /
+     * `ref` (`_<id>`), color-scheme slot → a `colorsByScheme` key. Token names are non-unique (two
+     * design assets can ship the same name) and renaming one must not break references, so matching
+     * by name is unsafe. Need a human-readable label? Read it from `list_theme_globals` (MCP/CLI) or
+     * the editor's Styles panel — not from the runtime getters.
+     */
+    name?: never;
+};
+export type RuntimeDesignToken = RuntimeView<DesignToken>;
+export type RuntimeTypographyToken = RuntimeView<TypographyToken>;
+export type RuntimeBreakpointToken = RuntimeView<BreakpointToken>;
+export type RuntimeKeyframeToken = RuntimeView<KeyframeToken>;
+export type RuntimeColorSchemeToken = RuntimeView<ColorSchemeToken>;
+export type RuntimeColorSchemeSlot = RuntimeView<ColorSchemeSlot>;
 /**
  * Runtime view of {@link ThemeGlobals.colorSchemes} (returned by `getThemeColorSchemes`). The
  * slot list carries only `{ id }`: slot display LABELS (the slot `name`) are authoring-only —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikas/bp-storefront",
-  "version": "1.4.0-beta.88",
+  "version": "1.4.0-beta.89",
   "description": "A framework for the ikas blueprint storefronts.",
   "author": "ikas",
   "license": "ISC",