@pixerate/editor 0.161.0 → 0.162.0

package/dist/typography/stack.d.cts

@@ -0,0 +1,26 @@
+/**
+ * CSS `font-family` stacks: parsing, formatting and cross-platform fallbacks.
+ */
+import type { FontCategory } from './types.cjs';
+/** Generic family keywords; these must stay unquoted in `font-family`. */
+export declare const GENERIC_FONT_FAMILIES: readonly string[];
+export type FontStackName = 'system-ui' | 'humanist-sans' | 'geometric-sans' | 'editorial-serif' | 'transitional-serif' | 'code-mono' | 'handwriting' | 'display';
+/** Tested cross-platform stacks, each ending in a generic family. */
+export declare const FONT_STACKS: Readonly<Record<FontStackName, string>>;
+export declare const FONT_STACK_NAMES: FontStackName[];
+/** The stack used as a fallback for each category. */
+export declare const CATEGORY_FALLBACK_STACK: Readonly<Record<FontCategory, FontStackName>>;
+/**
+ * Splits a CSS `font-family` value into unquoted family names. Handles single and double quotes,
+ * backslash escapes and commas inside quotes; collapses white space in unquoted names.
+ */
+export declare function parseFontFamily(stack: string): string[];
+/** Quotes a family name for CSS when it needs it (generic keywords are never quoted). */
+export declare function quoteFontFamily(name: string): string;
+/** Joins family names into a CSS `font-family` value, dropping duplicates (case-insensitive). */
+export declare function formatFontFamily(families: readonly string[]): string;
+/**
+ * A resilient `font-family` value for a family: the family (or every family of a stack passed
+ * in), then the stack for its category, ending in a generic family.
+ */
+export declare function resolveFontFallback(family: string, category?: FontCategory): string;

package/dist/typography/stack.d.ts

@@ -0,0 +1,26 @@
+/**
+ * CSS `font-family` stacks: parsing, formatting and cross-platform fallbacks.
+ */
+import type { FontCategory } from './types.js';
+/** Generic family keywords; these must stay unquoted in `font-family`. */
+export declare const GENERIC_FONT_FAMILIES: readonly string[];
+export type FontStackName = 'system-ui' | 'humanist-sans' | 'geometric-sans' | 'editorial-serif' | 'transitional-serif' | 'code-mono' | 'handwriting' | 'display';
+/** Tested cross-platform stacks, each ending in a generic family. */
+export declare const FONT_STACKS: Readonly<Record<FontStackName, string>>;
+export declare const FONT_STACK_NAMES: FontStackName[];
+/** The stack used as a fallback for each category. */
+export declare const CATEGORY_FALLBACK_STACK: Readonly<Record<FontCategory, FontStackName>>;
+/**
+ * Splits a CSS `font-family` value into unquoted family names. Handles single and double quotes,
+ * backslash escapes and commas inside quotes; collapses white space in unquoted names.
+ */
+export declare function parseFontFamily(stack: string): string[];
+/** Quotes a family name for CSS when it needs it (generic keywords are never quoted). */
+export declare function quoteFontFamily(name: string): string;
+/** Joins family names into a CSS `font-family` value, dropping duplicates (case-insensitive). */
+export declare function formatFontFamily(families: readonly string[]): string;
+/**
+ * A resilient `font-family` value for a family: the family (or every family of a stack passed
+ * in), then the stack for its category, ending in a generic family.
+ */
+export declare function resolveFontFallback(family: string, category?: FontCategory): string;

package/dist/typography/tools.d.cts

@@ -0,0 +1,34 @@
+/**
+ * Agent tools for typography: font discovery and fallback stacks, modular scales and hierarchies,
+ * fluid sizes, readability and accessibility audits, text segmentation, and a font picker.
+ */
+import type { AgentToolProvider } from '../tools/registry.cjs';
+import type { FontPickerModel } from './picker.cjs';
+import { type FontProvider } from './registry.cjs';
+export interface TypographyToolProviderOptions {
+    /** Provider id (unique per registry). Default 'typography'. */
+    id?: string;
+    /** Tool-name prefix; defaults to 'typography', '' for bare names. */
+    namespace?: string;
+    /** Where `list_fonts`, `resolve_font_stack` and `load_font` look. Default: the system font catalog. */
+    provider?: FontProvider;
+}
+/**
+ * An AgentToolProvider with font discovery, fallback stacks, type scales and hierarchies, fluid
+ * sizes, readability and type-aware contrast audits, and text segmentation. `load_font` is only
+ * listed when the font provider can load fonts.
+ */
+export declare function createTypographyToolProvider(options?: TypographyToolProviderOptions): AgentToolProvider;
+export interface FontPickerToolProviderOptions {
+    /** Provider id (unique per registry). Default 'font-picker'. */
+    id?: string;
+    /** Tool-name prefix; defaults to 'fontpicker', '' for bare names. */
+    namespace?: string;
+    /** Refuse `set_font_selection` (with this reason) while true; read tools still work. */
+    readOnly?: () => string | false;
+}
+/**
+ * Tools that read and change a mounted {@link FontPickerModel}, so an agent can choose a font in
+ * the same control a person uses.
+ */
+export declare function createFontPickerToolProvider(model: FontPickerModel, options?: FontPickerToolProviderOptions): AgentToolProvider;

package/dist/typography/tools.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Agent tools for typography: font discovery and fallback stacks, modular scales and hierarchies,
+ * fluid sizes, readability and accessibility audits, text segmentation, and a font picker.
+ */
+import type { AgentToolProvider } from '../tools/registry.js';
+import type { FontPickerModel } from './picker.js';
+import { type FontProvider } from './registry.js';
+export interface TypographyToolProviderOptions {
+    /** Provider id (unique per registry). Default 'typography'. */
+    id?: string;
+    /** Tool-name prefix; defaults to 'typography', '' for bare names. */
+    namespace?: string;
+    /** Where `list_fonts`, `resolve_font_stack` and `load_font` look. Default: the system font catalog. */
+    provider?: FontProvider;
+}
+/**
+ * An AgentToolProvider with font discovery, fallback stacks, type scales and hierarchies, fluid
+ * sizes, readability and type-aware contrast audits, and text segmentation. `load_font` is only
+ * listed when the font provider can load fonts.
+ */
+export declare function createTypographyToolProvider(options?: TypographyToolProviderOptions): AgentToolProvider;
+export interface FontPickerToolProviderOptions {
+    /** Provider id (unique per registry). Default 'font-picker'. */
+    id?: string;
+    /** Tool-name prefix; defaults to 'fontpicker', '' for bare names. */
+    namespace?: string;
+    /** Refuse `set_font_selection` (with this reason) while true; read tools still work. */
+    readOnly?: () => string | false;
+}
+/**
+ * Tools that read and change a mounted {@link FontPickerModel}, so an agent can choose a font in
+ * the same control a person uses.
+ */
+export declare function createFontPickerToolProvider(model: FontPickerModel, options?: FontPickerToolProviderOptions): AgentToolProvider;

package/dist/typography/types.d.cts

@@ -0,0 +1,96 @@
+/**
+ * Core typography types: font specs, weights, categories, scales and readability results.
+ */
+/** Numeric CSS font weights, 100–900 in steps of 100. */
+export type NumericFontWeight = 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
+/** A CSS font weight: numeric, or the `normal` (400) and `bold` (700) keywords. */
+export type FontWeight = NumericFontWeight | 'normal' | 'bold';
+export type FontStyle = 'normal' | 'italic' | 'oblique';
+/** Broad classification used for filtering and for choosing a fallback stack. */
+export type FontCategory = 'sans-serif' | 'serif' | 'monospace' | 'display' | 'handwriting';
+/** Where a font comes from: installed on the system, loaded over the web, or supplied by the host. */
+export type FontSource = 'system' | 'web' | 'custom';
+export declare const FONT_CATEGORIES: readonly FontCategory[];
+/** Display names for categories (and `all`), for filters and badges. */
+export declare const FONT_CATEGORY_LABELS: Readonly<Record<FontCategory | 'all', string>>;
+export declare const FONT_WEIGHTS: readonly NumericFontWeight[];
+export declare const FONT_STYLES: readonly FontStyle[];
+/** Normalized specification for a typographic style. */
+export interface FontSpec {
+    /** Primary family name, unquoted (e.g. `Inter`). Use `resolveFontFallback` for a CSS stack. */
+    family: string;
+    /** Default 400. */
+    weight?: FontWeight;
+    /** Default `normal`. */
+    style?: FontStyle;
+    /** Font size in CSS px. */
+    size: number;
+    /** Unitless line-height multiplier (1.5 = 150 % of `size`). */
+    lineHeight?: number;
+    /** Tracking in em (0.05 = 5 % of `size`). */
+    letterSpacing?: number;
+    category?: FontCategory;
+}
+/** Named modular scale ratios. */
+export type ModularScaleRatio = 'minor-second' | 'major-second' | 'minor-third' | 'major-third' | 'perfect-fourth' | 'augmented-fourth' | 'perfect-fifth' | 'golden-ratio';
+export interface TypeScaleStep {
+    /** Token name, e.g. `body`, `h1`, or `step-3` for an unnamed step. */
+    name: string;
+    /** Integer exponent; 0 is the base size. */
+    step: number;
+    /** Computed size in px (rounded to 0.01). */
+    size: number;
+    /** Recommended unitless line-height. */
+    lineHeight: number;
+    /** Recommended tracking in em. */
+    letterSpacing: number;
+}
+export interface TypeHierarchy {
+    ratio: number;
+    /** The named ratio, when one was used. */
+    ratioName?: ModularScaleRatio;
+    baseSize: number;
+    steps: Record<string, TypeScaleStep>;
+}
+export interface ReadabilityAuditResult {
+    lineLength: {
+        /** Average characters (grapheme clusters) per line. */
+        characters: number;
+        /** Average words per line. */
+        words: number;
+        /** `lines` when measured from the text's own line breaks, `width` when estimated from a container width. */
+        source: 'lines' | 'width';
+        /** Optimal is 45–75 characters. */
+        status: 'optimal' | 'too-short' | 'too-long';
+        recommendation?: string;
+    };
+    lineSpacing: {
+        /** Line-height multiplier used (1.2 when none was given: the browser `normal` approximation). */
+        ratio: number;
+        /** True when `ratio` was not given. */
+        assumed: boolean;
+        /** Line spacing is at least 1.5 (WCAG 1.4.8 / 1.4.12 body-text value). */
+        meetsRecommended: boolean;
+        recommendation?: string;
+    };
+    /** The text is set in capitals (two or more letters, none lower case). */
+    allCaps: boolean;
+    wordCount: number;
+    /** Silent reading at 238 words per minute. */
+    estimatedReadingTimeSeconds: number;
+    /** Human-readable findings, empty when nothing needs attention. */
+    issues: string[];
+}
+/** One piece of text from `segmentText`, with UTF-16 offsets into the original string. */
+export interface TextSegment {
+    text: string;
+    /** UTF-16 offset of the first code unit. */
+    start: number;
+    /** UTF-16 offset just past the last code unit. */
+    end: number;
+    /** Position in the returned list. */
+    index: number;
+    /** For `word` granularity: whether the segment is a word (not white space or punctuation). */
+    isWordLike?: boolean;
+}
+export type SegmentGranularity = 'grapheme' | 'word' | 'sentence' | 'line';

package/dist/typography/types.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Core typography types: font specs, weights, categories, scales and readability results.
+ */
+/** Numeric CSS font weights, 100–900 in steps of 100. */
+export type NumericFontWeight = 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
+/** A CSS font weight: numeric, or the `normal` (400) and `bold` (700) keywords. */
+export type FontWeight = NumericFontWeight | 'normal' | 'bold';
+export type FontStyle = 'normal' | 'italic' | 'oblique';
+/** Broad classification used for filtering and for choosing a fallback stack. */
+export type FontCategory = 'sans-serif' | 'serif' | 'monospace' | 'display' | 'handwriting';
+/** Where a font comes from: installed on the system, loaded over the web, or supplied by the host. */
+export type FontSource = 'system' | 'web' | 'custom';
+export declare const FONT_CATEGORIES: readonly FontCategory[];
+/** Display names for categories (and `all`), for filters and badges. */
+export declare const FONT_CATEGORY_LABELS: Readonly<Record<FontCategory | 'all', string>>;
+export declare const FONT_WEIGHTS: readonly NumericFontWeight[];
+export declare const FONT_STYLES: readonly FontStyle[];
+/** Normalized specification for a typographic style. */
+export interface FontSpec {
+    /** Primary family name, unquoted (e.g. `Inter`). Use `resolveFontFallback` for a CSS stack. */
+    family: string;
+    /** Default 400. */
+    weight?: FontWeight;
+    /** Default `normal`. */
+    style?: FontStyle;
+    /** Font size in CSS px. */
+    size: number;
+    /** Unitless line-height multiplier (1.5 = 150 % of `size`). */
+    lineHeight?: number;
+    /** Tracking in em (0.05 = 5 % of `size`). */
+    letterSpacing?: number;
+    category?: FontCategory;
+}
+/** Named modular scale ratios. */
+export type ModularScaleRatio = 'minor-second' | 'major-second' | 'minor-third' | 'major-third' | 'perfect-fourth' | 'augmented-fourth' | 'perfect-fifth' | 'golden-ratio';
+export interface TypeScaleStep {
+    /** Token name, e.g. `body`, `h1`, or `step-3` for an unnamed step. */
+    name: string;
+    /** Integer exponent; 0 is the base size. */
+    step: number;
+    /** Computed size in px (rounded to 0.01). */
+    size: number;
+    /** Recommended unitless line-height. */
+    lineHeight: number;
+    /** Recommended tracking in em. */
+    letterSpacing: number;
+}
+export interface TypeHierarchy {
+    ratio: number;
+    /** The named ratio, when one was used. */
+    ratioName?: ModularScaleRatio;
+    baseSize: number;
+    steps: Record<string, TypeScaleStep>;
+}
+export interface ReadabilityAuditResult {
+    lineLength: {
+        /** Average characters (grapheme clusters) per line. */
+        characters: number;
+        /** Average words per line. */
+        words: number;
+        /** `lines` when measured from the text's own line breaks, `width` when estimated from a container width. */
+        source: 'lines' | 'width';
+        /** Optimal is 45–75 characters. */
+        status: 'optimal' | 'too-short' | 'too-long';
+        recommendation?: string;
+    };
+    lineSpacing: {
+        /** Line-height multiplier used (1.2 when none was given: the browser `normal` approximation). */
+        ratio: number;
+        /** True when `ratio` was not given. */
+        assumed: boolean;
+        /** Line spacing is at least 1.5 (WCAG 1.4.8 / 1.4.12 body-text value). */
+        meetsRecommended: boolean;
+        recommendation?: string;
+    };
+    /** The text is set in capitals (two or more letters, none lower case). */
+    allCaps: boolean;
+    wordCount: number;
+    /** Silent reading at 238 words per minute. */
+    estimatedReadingTimeSeconds: number;
+    /** Human-readable findings, empty when nothing needs attention. */
+    issues: string[];
+}
+/** One piece of text from `segmentText`, with UTF-16 offsets into the original string. */
+export interface TextSegment {
+    text: string;
+    /** UTF-16 offset of the first code unit. */
+    start: number;
+    /** UTF-16 offset just past the last code unit. */
+    end: number;
+    /** Position in the returned list. */
+    index: number;
+    /** For `word` granularity: whether the segment is a word (not white space or punctuation). */
+    isWordLike?: boolean;
+}
+export type SegmentGranularity = 'grapheme' | 'word' | 'sentence' | 'line';

package/dist/typography/weight.d.cts

@@ -0,0 +1,13 @@
+/**
+ * Font weight normalisation and matching.
+ */
+import type { FontWeight, NumericFontWeight } from './types.cjs';
+/** `normal` → 400, `bold` → 700, numbers rounded to the nearest 100 within 100–900. */
+export declare function normalizeFontWeight(weight: FontWeight | number | undefined): NumericFontWeight;
+/** Whether a value is a CSS font weight this module accepts. */
+export declare function isFontWeight(value: unknown): value is FontWeight;
+/**
+ * The available weight CSS font matching would pick for `wanted`: for 400 try 500 first, then
+ * lighter, then heavier; below 400 lighter first; above 500 heavier first.
+ */
+export declare function nearestFontWeight(wanted: FontWeight | number, available: readonly FontWeight[]): NumericFontWeight;

package/dist/typography/weight.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Font weight normalisation and matching.
+ */
+import type { FontWeight, NumericFontWeight } from './types.js';
+/** `normal` → 400, `bold` → 700, numbers rounded to the nearest 100 within 100–900. */
+export declare function normalizeFontWeight(weight: FontWeight | number | undefined): NumericFontWeight;
+/** Whether a value is a CSS font weight this module accepts. */
+export declare function isFontWeight(value: unknown): value is FontWeight;
+/**
+ * The available weight CSS font matching would pick for `wanted`: for 400 try 500 first, then
+ * lighter, then heavier; below 400 lighter first; above 500 heavier first.
+ */
+export declare function nearestFontWeight(wanted: FontWeight | number, available: readonly FontWeight[]): NumericFontWeight;