@pixerate/editor 0.163.0 → 0.165.0

package/dist/tools/style.d.cts

@@ -0,0 +1,212 @@
+/**
+ * House-style skills: preferences and rules a host hands agents at runtime, per editor domain.
+ *
+ * A style skill is a folder like a built-in agent skill: a `SKILL.md` of prose preferences
+ * (frontmatter `name`, `description` and optionally `domains`) plus one optional profile per
+ * domain (`chart.json`, `tokens.json`) holding structured rules. Hosts keep style skills in
+ * layers (org, workspace, user, ...); a {@link StyleResolver} merges them per domain, resolves
+ * `$token` references and runs the domain's checks. Dependency-free: domains bring their own
+ * profile schema and checks (`chartStyleDomain`, `tokensStyleDomain`).
+ */
+import { type JsonSchema } from './schema.cjs';
+import { type SkillFiles } from './skills.cjs';
+type MaybePromise<T> = T | Promise<T>;
+/** What a store records about one style skill, apart from its files. */
+export interface StyleSkillState {
+    /** `false` switches the skill off (also for a skill another layer holds). Default on. */
+    enabled?: boolean;
+    /** Sort key among skills of the same layer (lower first, default 0). */
+    order?: number;
+}
+/** One entry of {@link StyleStore.list}: a skill this store holds, or state for another layer's. */
+export interface StyleStoreEntry extends StyleSkillState {
+    name: string;
+}
+/**
+ * Where one layer's style skills live. Hosts implement it over their own storage (a database,
+ * a bucket, the file system); {@link memoryStyleStore} holds skills in memory.
+ */
+export interface StyleStore {
+    /** Skill names with their state. An entry whose `SKILL.md` this store lacks only carries state. */
+    list(): MaybePromise<readonly StyleStoreEntry[]>;
+    /** A file of a skill (`SKILL.md`, `chart.json`, `references/x.md`), or `undefined`. */
+    read(name: string, file: string): MaybePromise<string | undefined>;
+    /** Every file of a skill, relative to its folder. */
+    files(name: string): MaybePromise<readonly string[]>;
+    /** Called when the store's skills or state change; returns an unsubscribe function. */
+    subscribe?(listener: () => void): () => void;
+}
+/** A layer of style skills, from general (first) to specific (last). */
+export interface StyleLayer {
+    /** Layer id, shown to agents as where a rule came from: `org`, `workspace`, `user`, ... */
+    id: string;
+    store: StyleStore;
+    /**
+     * Later layers cannot replace this layer's skills or change the profile fields it sets.
+     * Their attempts are left out and reported as issues.
+     */
+    locked?: boolean;
+    /** Later layers cannot switch this layer's skills off. */
+    required?: boolean;
+}
+/** A finding: one house-style rule the current state breaks. */
+export interface StyleFinding {
+    /** Id of the check that found it. */
+    check: string;
+    severity: 'error' | 'warning' | 'info';
+    /** What is wrong and how to fix it, in one sentence. */
+    message: string;
+    /** What it is about, in the shape the domain's write tools take (e.g. a chart selection). */
+    target?: unknown;
+    /** The layer whose profile asked for the check. */
+    layer?: string;
+}
+/**
+ * A rule a domain can check. A profile turns it on by id in its `checks` list, with options:
+ * `"palette-only"` or `{ "id": "min-contrast", "ratio": 4.5 }`.
+ */
+export interface StyleCheck<State = unknown> {
+    id: string;
+    /** What it checks, for agents and admin screens. */
+    description: string;
+    /** Schema of its options (validated when a profile loads). Default: no options. */
+    optionsSchema?: JsonSchema;
+    /** The findings for `state` under the resolved `profile`. Throwing reports the check as skipped. */
+    run(state: State, profile: Readonly<Record<string, unknown>>, options: Readonly<Record<string, unknown>>): readonly Omit<StyleFinding, 'check' | 'layer'>[];
+}
+/** An editor domain that can have a house style: its profile file, schema and checks. */
+export interface StyleDomain<State = unknown> {
+    /** Domain id, the domain skill's name without `pixerate-` (`chart`, `tokens`). The profile file is `<id>.json`. */
+    id: string;
+    title: string;
+    /** What a profile for this domain can set. */
+    description: string;
+    /** Schema of the profile (the `checks` property is validated separately). */
+    profileSchema: JsonSchema & {
+        type: 'object';
+    };
+    checks: readonly StyleCheck<State>[];
+}
+/** A `$token` reference in a profile: `{ "$token": "brand/primary", "mode": "Dark" }`. */
+export interface StyleTokenRef {
+    /** Variable name (`brand/primary`) or id. */
+    token: string;
+    /** Mode name or id (default: the collection's default mode). */
+    mode?: string;
+}
+/** Resolves `$token` references in profiles (see `createTokenStyleSource` in `@pixerate/editor/tokens`). */
+export interface StyleTokenSource {
+    /** The value, or an error saying why the reference does not resolve. */
+    resolve(ref: StyleTokenRef): {
+        ok: true;
+        value: string | number | boolean;
+    } | {
+        ok: false;
+        message: string;
+    };
+    subscribe?(listener: () => void): () => void;
+}
+export interface StyleIssue {
+    /** Skill the issue is about (absent for layer-wide issues). */
+    skill?: string;
+    layer?: string;
+    message: string;
+}
+/** A style skill as a resolver lists it. */
+export interface StyleSkillInfo {
+    name: string;
+    description: string;
+    /** The layer whose copy is used. */
+    layer: string;
+    /** Domains it applies to (every registered domain when its frontmatter names none). */
+    domains: string[];
+    /** Domains it has a profile for. */
+    profiles: string[];
+    enabled: boolean;
+    order: number;
+    /** Why it, or part of it, is left out. A skill with issues and no usable part is not applied. */
+    issues: string[];
+}
+/** A skill's prose as it applies to one domain. */
+export interface ResolvedStyleSkill {
+    name: string;
+    description: string;
+    layer: string;
+    /** The `SKILL.md` body (without frontmatter). */
+    body: string;
+}
+/** Everything that applies to one domain, merged. */
+export interface ResolvedStyle {
+    domain: string;
+    /** Applicable skills, general to specific. */
+    skills: ResolvedStyleSkill[];
+    /** The merged profile, with `$token` references replaced by their values. */
+    profile: Record<string, unknown>;
+    /** Which layer set each profile field (`palette`, `theme.fontFamily`). */
+    sources: Record<string, string>;
+    issues: StyleIssue[];
+}
+/** The result of running a domain's checks. */
+export interface StyleCheckReport {
+    findings: StyleFinding[];
+    /** Checks that ran. */
+    ran: string[];
+    /** Checks the profile asked for that could not run, with the reason. */
+    skipped: {
+        check: string;
+        reason: string;
+    }[];
+}
+export interface StyleResolverOptions {
+    /** Layers from general to specific. */
+    layers: readonly StyleLayer[];
+    /** Domains style skills may target. */
+    domains: readonly StyleDomain<any>[];
+    /** Resolves `$token` references; without it a profile with one is reported as an issue. */
+    tokens?: StyleTokenSource;
+}
+/** Merges house-style layers per domain. Build it with {@link createStyleResolver}. */
+export interface StyleResolver {
+    readonly layers: readonly StyleLayer[];
+    readonly domains: readonly StyleDomain<any>[];
+    /** Every style skill across layers (switched-off ones too), general to specific. */
+    list(options?: {
+        domain?: string;
+    }): Promise<StyleSkillInfo[]>;
+    /** The resolved style for a domain. Throws for an unknown domain. */
+    resolve(domain: string): Promise<ResolvedStyle>;
+    /** A file of the skill copy in use. */
+    readFile(name: string, file: string): Promise<string | undefined>;
+    /** Files of the skill copy in use (`undefined` for an unknown skill). */
+    files(name: string): Promise<string[] | undefined>;
+    /** Runs the domain's checks that the resolved profile turns on against `state`. */
+    check<State>(domain: string, state: State): Promise<StyleCheckReport & {
+        style: ResolvedStyle;
+    }>;
+    /** Called when a store or the token source changes; returns an unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+}
+/** The `domains` frontmatter field: `[chart, tokens]`, `chart, tokens` or one name. */
+export declare function parseStyleDomains(markdown: string): string[] | undefined;
+/**
+ * A style store in memory, from skill files keyed `<skill>/<file>` (the {@link SkillFiles}
+ * shape), with optional state per skill. `set`, `remove` and `setState` notify subscribers.
+ */
+export declare function memoryStyleStore(initial?: SkillFiles, state?: Readonly<Record<string, StyleSkillState>>): StyleStore & {
+    set(name: string, files: Readonly<Record<string, string>>): void;
+    remove(name: string): void;
+    setState(name: string, state: StyleSkillState | undefined): void;
+};
+/**
+ * Builds a {@link StyleResolver} over layers of style skills. Reads go to the stores on every
+ * call, so a host's change shows up at once; `subscribe` tells open views to refresh.
+ */
+export declare function createStyleResolver(options: StyleResolverOptions): StyleResolver;
+/** Runs the checks a resolved profile turns on. A check that is unknown or throws is skipped with the reason. */
+export declare function runStyleChecks<State>(domain: StyleDomain<State>, state: State, style: ResolvedStyle): StyleCheckReport;
+/**
+ * A resolved style as text for a model: one `<style_skill>` block per skill (naming its layer;
+ * text that tries to open or close a block is escaped) and the merged profile as JSON.
+ */
+export declare function renderStyle(style: ResolvedStyle): string;
+export {};

package/dist/tools/style.d.ts

@@ -0,0 +1,212 @@
+/**
+ * House-style skills: preferences and rules a host hands agents at runtime, per editor domain.
+ *
+ * A style skill is a folder like a built-in agent skill: a `SKILL.md` of prose preferences
+ * (frontmatter `name`, `description` and optionally `domains`) plus one optional profile per
+ * domain (`chart.json`, `tokens.json`) holding structured rules. Hosts keep style skills in
+ * layers (org, workspace, user, ...); a {@link StyleResolver} merges them per domain, resolves
+ * `$token` references and runs the domain's checks. Dependency-free: domains bring their own
+ * profile schema and checks (`chartStyleDomain`, `tokensStyleDomain`).
+ */
+import { type JsonSchema } from './schema.js';
+import { type SkillFiles } from './skills.js';
+type MaybePromise<T> = T | Promise<T>;
+/** What a store records about one style skill, apart from its files. */
+export interface StyleSkillState {
+    /** `false` switches the skill off (also for a skill another layer holds). Default on. */
+    enabled?: boolean;
+    /** Sort key among skills of the same layer (lower first, default 0). */
+    order?: number;
+}
+/** One entry of {@link StyleStore.list}: a skill this store holds, or state for another layer's. */
+export interface StyleStoreEntry extends StyleSkillState {
+    name: string;
+}
+/**
+ * Where one layer's style skills live. Hosts implement it over their own storage (a database,
+ * a bucket, the file system); {@link memoryStyleStore} holds skills in memory.
+ */
+export interface StyleStore {
+    /** Skill names with their state. An entry whose `SKILL.md` this store lacks only carries state. */
+    list(): MaybePromise<readonly StyleStoreEntry[]>;
+    /** A file of a skill (`SKILL.md`, `chart.json`, `references/x.md`), or `undefined`. */
+    read(name: string, file: string): MaybePromise<string | undefined>;
+    /** Every file of a skill, relative to its folder. */
+    files(name: string): MaybePromise<readonly string[]>;
+    /** Called when the store's skills or state change; returns an unsubscribe function. */
+    subscribe?(listener: () => void): () => void;
+}
+/** A layer of style skills, from general (first) to specific (last). */
+export interface StyleLayer {
+    /** Layer id, shown to agents as where a rule came from: `org`, `workspace`, `user`, ... */
+    id: string;
+    store: StyleStore;
+    /**
+     * Later layers cannot replace this layer's skills or change the profile fields it sets.
+     * Their attempts are left out and reported as issues.
+     */
+    locked?: boolean;
+    /** Later layers cannot switch this layer's skills off. */
+    required?: boolean;
+}
+/** A finding: one house-style rule the current state breaks. */
+export interface StyleFinding {
+    /** Id of the check that found it. */
+    check: string;
+    severity: 'error' | 'warning' | 'info';
+    /** What is wrong and how to fix it, in one sentence. */
+    message: string;
+    /** What it is about, in the shape the domain's write tools take (e.g. a chart selection). */
+    target?: unknown;
+    /** The layer whose profile asked for the check. */
+    layer?: string;
+}
+/**
+ * A rule a domain can check. A profile turns it on by id in its `checks` list, with options:
+ * `"palette-only"` or `{ "id": "min-contrast", "ratio": 4.5 }`.
+ */
+export interface StyleCheck<State = unknown> {
+    id: string;
+    /** What it checks, for agents and admin screens. */
+    description: string;
+    /** Schema of its options (validated when a profile loads). Default: no options. */
+    optionsSchema?: JsonSchema;
+    /** The findings for `state` under the resolved `profile`. Throwing reports the check as skipped. */
+    run(state: State, profile: Readonly<Record<string, unknown>>, options: Readonly<Record<string, unknown>>): readonly Omit<StyleFinding, 'check' | 'layer'>[];
+}
+/** An editor domain that can have a house style: its profile file, schema and checks. */
+export interface StyleDomain<State = unknown> {
+    /** Domain id, the domain skill's name without `pixerate-` (`chart`, `tokens`). The profile file is `<id>.json`. */
+    id: string;
+    title: string;
+    /** What a profile for this domain can set. */
+    description: string;
+    /** Schema of the profile (the `checks` property is validated separately). */
+    profileSchema: JsonSchema & {
+        type: 'object';
+    };
+    checks: readonly StyleCheck<State>[];
+}
+/** A `$token` reference in a profile: `{ "$token": "brand/primary", "mode": "Dark" }`. */
+export interface StyleTokenRef {
+    /** Variable name (`brand/primary`) or id. */
+    token: string;
+    /** Mode name or id (default: the collection's default mode). */
+    mode?: string;
+}
+/** Resolves `$token` references in profiles (see `createTokenStyleSource` in `@pixerate/editor/tokens`). */
+export interface StyleTokenSource {
+    /** The value, or an error saying why the reference does not resolve. */
+    resolve(ref: StyleTokenRef): {
+        ok: true;
+        value: string | number | boolean;
+    } | {
+        ok: false;
+        message: string;
+    };
+    subscribe?(listener: () => void): () => void;
+}
+export interface StyleIssue {
+    /** Skill the issue is about (absent for layer-wide issues). */
+    skill?: string;
+    layer?: string;
+    message: string;
+}
+/** A style skill as a resolver lists it. */
+export interface StyleSkillInfo {
+    name: string;
+    description: string;
+    /** The layer whose copy is used. */
+    layer: string;
+    /** Domains it applies to (every registered domain when its frontmatter names none). */
+    domains: string[];
+    /** Domains it has a profile for. */
+    profiles: string[];
+    enabled: boolean;
+    order: number;
+    /** Why it, or part of it, is left out. A skill with issues and no usable part is not applied. */
+    issues: string[];
+}
+/** A skill's prose as it applies to one domain. */
+export interface ResolvedStyleSkill {
+    name: string;
+    description: string;
+    layer: string;
+    /** The `SKILL.md` body (without frontmatter). */
+    body: string;
+}
+/** Everything that applies to one domain, merged. */
+export interface ResolvedStyle {
+    domain: string;
+    /** Applicable skills, general to specific. */
+    skills: ResolvedStyleSkill[];
+    /** The merged profile, with `$token` references replaced by their values. */
+    profile: Record<string, unknown>;
+    /** Which layer set each profile field (`palette`, `theme.fontFamily`). */
+    sources: Record<string, string>;
+    issues: StyleIssue[];
+}
+/** The result of running a domain's checks. */
+export interface StyleCheckReport {
+    findings: StyleFinding[];
+    /** Checks that ran. */
+    ran: string[];
+    /** Checks the profile asked for that could not run, with the reason. */
+    skipped: {
+        check: string;
+        reason: string;
+    }[];
+}
+export interface StyleResolverOptions {
+    /** Layers from general to specific. */
+    layers: readonly StyleLayer[];
+    /** Domains style skills may target. */
+    domains: readonly StyleDomain<any>[];
+    /** Resolves `$token` references; without it a profile with one is reported as an issue. */
+    tokens?: StyleTokenSource;
+}
+/** Merges house-style layers per domain. Build it with {@link createStyleResolver}. */
+export interface StyleResolver {
+    readonly layers: readonly StyleLayer[];
+    readonly domains: readonly StyleDomain<any>[];
+    /** Every style skill across layers (switched-off ones too), general to specific. */
+    list(options?: {
+        domain?: string;
+    }): Promise<StyleSkillInfo[]>;
+    /** The resolved style for a domain. Throws for an unknown domain. */
+    resolve(domain: string): Promise<ResolvedStyle>;
+    /** A file of the skill copy in use. */
+    readFile(name: string, file: string): Promise<string | undefined>;
+    /** Files of the skill copy in use (`undefined` for an unknown skill). */
+    files(name: string): Promise<string[] | undefined>;
+    /** Runs the domain's checks that the resolved profile turns on against `state`. */
+    check<State>(domain: string, state: State): Promise<StyleCheckReport & {
+        style: ResolvedStyle;
+    }>;
+    /** Called when a store or the token source changes; returns an unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+}
+/** The `domains` frontmatter field: `[chart, tokens]`, `chart, tokens` or one name. */
+export declare function parseStyleDomains(markdown: string): string[] | undefined;
+/**
+ * A style store in memory, from skill files keyed `<skill>/<file>` (the {@link SkillFiles}
+ * shape), with optional state per skill. `set`, `remove` and `setState` notify subscribers.
+ */
+export declare function memoryStyleStore(initial?: SkillFiles, state?: Readonly<Record<string, StyleSkillState>>): StyleStore & {
+    set(name: string, files: Readonly<Record<string, string>>): void;
+    remove(name: string): void;
+    setState(name: string, state: StyleSkillState | undefined): void;
+};
+/**
+ * Builds a {@link StyleResolver} over layers of style skills. Reads go to the stores on every
+ * call, so a host's change shows up at once; `subscribe` tells open views to refresh.
+ */
+export declare function createStyleResolver(options: StyleResolverOptions): StyleResolver;
+/** Runs the checks a resolved profile turns on. A check that is unknown or throws is skipped with the reason. */
+export declare function runStyleChecks<State>(domain: StyleDomain<State>, state: State, style: ResolvedStyle): StyleCheckReport;
+/**
+ * A resolved style as text for a model: one `<style_skill>` block per skill (naming its layer;
+ * text that tries to open or close a block is escaped) and the merged profile as JSON.
+ */
+export declare function renderStyle(style: ResolvedStyle): string;
+export {};

package/dist/tools/view.d.cts

@@ -1,5 +1,6 @@
 import type { McpListToolsResult, McpToolDefinition, McpToolResult, ToolCallOptions, ToolSource, ToolsetInfo } from './registry.cjs';
 import { type SkillFiles } from './skills.cjs';
+import type { StyleResolver } from './style.cjs';
 export interface ToolDiscoveryOptions {
     /** Toolsets listed from the start (default none: the agent enables what it needs). */
     enabled?: readonly string[];
@@ -7,6 +8,11 @@ export interface ToolDiscoveryOptions {
     skills?: SkillFiles;
     /** Default and maximum number of `search_tools` results (default 10, at most 50). */
     searchLimit?: number;
+    /**
+     * House styles: `list_toolsets` marks each toolset whose domain (its skill's name without
+     * `pixerate-`) has style skills, and `enable_tools` says to read them with `get_style`.
+     */
+    styles?: StyleResolver;
 }
 export interface ToolViewOptions {
     /**

package/dist/tools/view.d.ts

@@ -1,5 +1,6 @@
 import type { McpListToolsResult, McpToolDefinition, McpToolResult, ToolCallOptions, ToolSource, ToolsetInfo } from './registry.js';
 import { type SkillFiles } from './skills.js';
+import type { StyleResolver } from './style.js';
 export interface ToolDiscoveryOptions {
     /** Toolsets listed from the start (default none: the agent enables what it needs). */
     enabled?: readonly string[];
@@ -7,6 +8,11 @@ export interface ToolDiscoveryOptions {
     skills?: SkillFiles;
     /** Default and maximum number of `search_tools` results (default 10, at most 50). */
     searchLimit?: number;
+    /**
+     * House styles: `list_toolsets` marks each toolset whose domain (its skill's name without
+     * `pixerate-`) has style skills, and `enable_tools` says to read them with `get_style`.
+     */
+    styles?: StyleResolver;
 }
 export interface ToolViewOptions {
     /**

package/dist/typography/index.cjs

@@ -18,10 +18,12 @@
 var _chunkFKUKJ3XAcjs = require('../chunk-FKUKJ3XA.cjs');
 
 
+var _chunkTFF2GTGNcjs = require('../chunk-TFF2GTGN.cjs');
 
 
 
-var _chunkS6X2QRVUcjs = require('../chunk-S6X2QRVU.cjs');
+
+var _chunk5UEFBM2Mcjs = require('../chunk-5UEFBM2M.cjs');
 require('../chunk-IPJ3TEYR.cjs');
 
 // src/typography/types.ts
@@ -418,13 +420,13 @@ function isLargeText(font) {
 function checkTypographyAccessibility(options) {
   const { font } = options;
   if (!Number.isFinite(font.size) || font.size <= 0) throw new Error(`Font size ${font.size} must be a positive number of px.`);
-  const fg = _chunkS6X2QRVUcjs.parseColor.call(void 0, options.foreground);
+  const fg = _chunk5UEFBM2Mcjs.parseColor.call(void 0, options.foreground);
   if (!fg) throw new Error(`"${options.foreground}" is not a colour I can read; use hex (#2a4b8d), rgb(), hsl(), oklch() or a CSS colour name.`);
-  const bg = _chunkS6X2QRVUcjs.parseColor.call(void 0, options.background);
+  const bg = _chunk5UEFBM2Mcjs.parseColor.call(void 0, options.background);
   if (!bg) throw new Error(`"${options.background}" is not a colour I can read; use hex (#ffffff), rgb(), hsl(), oklch() or a CSS colour name.`);
   const large = isLargeText(font);
-  const ratio = Math.round(_chunkS6X2QRVUcjs.contrastRatio.call(void 0, fg, bg) * 100) / 100;
-  const level = _chunkS6X2QRVUcjs.contrastLevel.call(void 0, ratio, { large });
+  const ratio = Math.round(_chunk5UEFBM2Mcjs.contrastRatio.call(void 0, fg, bg) * 100) / 100;
+  const level = _chunk5UEFBM2Mcjs.contrastLevel.call(void 0, ratio, { large });
   const passesAA = level !== "fail";
   const bold = _chunkFKUKJ3XAcjs.normalizeFontWeight.call(void 0, font.weight) >= 700;
   const issues = [];
@@ -433,7 +435,7 @@ function checkTypographyAccessibility(options) {
   if (font.size < 12) issues.push(`${font.size}px text is hard to read at any contrast; use 12px or more (16px for body text).`);
   const weight = _chunkFKUKJ3XAcjs.normalizeFontWeight.call(void 0, font.weight);
   if (weight <= 300 && font.size < 24) issues.push(`Weight ${weight} at ${font.size}px has thin strokes that lower effective contrast; use 400 or heavier below 24px.`);
-  const suggestion = passesAA ? void 0 : _chunkS6X2QRVUcjs.suggestAccessibleForeground.call(void 0, fg, bg, { large });
+  const suggestion = passesAA ? void 0 : _chunkTFF2GTGNcjs.suggestAccessibleForeground.call(void 0, fg, bg, { large });
   return {
     ratio,
     large,

package/dist/typography/index.js

@@ -16,12 +16,14 @@ import {
   normalizeFontWeight,
   webFontSummary
 } from "../chunk-CJE5MOIS.js";
+import {
+  suggestAccessibleForeground
+} from "../chunk-YBAPT7NL.js";
 import {
   contrastLevel,
   contrastRatio,
-  parseColor,
-  suggestAccessibleForeground
-} from "../chunk-4VU4CP7R.js";
+  parseColor
+} from "../chunk-MHLU6GRJ.js";
 import "../chunk-6ONMQ6WF.js";
 
 // src/typography/types.ts