@guideshot/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GuideShot contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,15 @@
+# @guideshot/core
+
+The portable GuideShot compiler: configuration contracts, recipe discovery, deterministic planning, resolution, diagnostics, hashing, and manifests.
+
+```sh
+pnpm add @guideshot/core
+```
+
+```ts
+import { parseRecipe } from '@guideshot/core';
+
+const recipe = parseRecipe(source, { file: 'example.shot.json' });
+```
+
+Browser drivers and annotation renderers are injected through `defineConfig`. Requires Node.js 20 or newer and is licensed under the MIT License.

package/dist/index.d.ts

@@ -0,0 +1,408 @@
+import { VariantValue, JsonObject, Annotation, Action, Expectation, Recipe, JsonValue, OutputFormat as OutputFormat$1, PublicManifest, LocalizedText } from '@guideshot/schema';
+export { Accessibility, Action, Annotation, AnnotationPlacement, Expectation, Frame, JsonObject, JsonValue, LocalizedText, ManifestEntry, ManifestVariant, Matrix, Output, OutputFormat, PublicManifest, PublicManifestSchema, Recipe, RecipeSchema, SCHEMA_VERSION, VariantValue } from '@guideshot/schema';
+
+declare function canonicalSerialize(value: unknown): string;
+declare function sha256(value: string | Uint8Array): string;
+declare function hashCanonical(value: unknown): string;
+declare function createCaptureHash(intent: unknown): string;
+declare function createCompositionHash(intent: unknown): string;
+
+interface ExtensionInfo {
+    name: string;
+    version: string;
+    apiVersion?: number;
+}
+interface Viewport {
+    width: number;
+    height: number;
+}
+interface CaptureProfile {
+    viewport: Viewport;
+    pixelRatio?: number;
+    locale?: string;
+    timezoneId?: string;
+    colorScheme?: 'light' | 'dark';
+    reducedMotion?: 'reduce' | 'no-preference';
+}
+interface BrowserCookie {
+    name: string;
+    value: string;
+    url?: string;
+    domain?: string;
+    path?: string;
+    expires?: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+}
+interface LocalStorageState {
+    origin: string;
+    values: Record<string, string>;
+}
+interface BrowserStatePatch {
+    locale?: string;
+    timezoneId?: string;
+    colorScheme?: 'light' | 'dark';
+    reducedMotion?: 'reduce' | 'no-preference';
+    cookies?: readonly BrowserCookie[];
+    localStorage?: readonly LocalStorageState[];
+    extraHTTPHeaders?: Readonly<Record<string, string>>;
+}
+interface DimensionResolveContext {
+    dimension: string;
+    variants: Readonly<Record<string, VariantValue>>;
+    signal?: AbortSignal;
+}
+interface DimensionDefinition<TValue extends VariantValue = VariantValue> extends ExtensionInfo {
+    values: readonly TValue[];
+    resolve(value: TValue, context: DimensionResolveContext): BrowserStatePatch | Promise<BrowserStatePatch>;
+}
+interface ScenarioContext {
+    baseUrl: URL;
+    recipeId: string;
+    variantKey: string;
+    variants: Readonly<Record<string, VariantValue>>;
+    fetch: typeof globalThis.fetch;
+    signal?: AbortSignal;
+}
+interface ScenarioResult {
+    variables?: JsonObject;
+    browser?: BrowserStatePatch;
+    cleanup?: () => void | Promise<void>;
+}
+interface ScenarioDefinition<TInput extends JsonObject = JsonObject> extends ExtensionInfo {
+    schema: object;
+    datasetRevision?: string;
+    prepare(context: ScenarioContext, input: TInput): ScenarioResult | Promise<ScenarioResult>;
+}
+interface TranslationContext {
+    locale: string;
+    args: Readonly<Record<string, JsonValue>>;
+    variables: Readonly<JsonObject>;
+}
+interface TranslationProvider extends ExtensionInfo {
+    resolve(message: string, context: TranslationContext): string | Promise<string>;
+}
+interface ServerConfig {
+    url: string;
+    command?: string;
+    timeoutMs?: number;
+}
+interface SafetyConfig {
+    allowedOrigins?: readonly string[];
+}
+interface GuideShotConfig {
+    recipes: readonly string[];
+    outputDir: string;
+    cacheDir: string;
+    server: ServerConfig;
+    safety?: SafetyConfig;
+    targetAttribute?: `data-${string}`;
+    profiles: Readonly<Record<string, CaptureProfile>>;
+    dimensions?: Readonly<Record<string, DimensionDefinition>>;
+    scenarios?: Readonly<Record<string, ScenarioDefinition>>;
+    translations?: TranslationProvider;
+    driver: BrowserDriver;
+    renderer: AnnotationRenderer;
+}
+interface BrowserEnvironment {
+    driver: string;
+    driverVersion: string;
+    browser: string;
+    browserVersion: string;
+    platform?: string;
+}
+interface DriverRunOptions {
+    baseUrl: URL;
+    targetAttribute: `data-${string}`;
+    signal?: AbortSignal;
+}
+interface ResolvedCaptureJob {
+    key: string;
+    recipeId: string;
+    variantKey: string;
+    variants: Readonly<Record<string, VariantValue>>;
+    profile: CaptureProfile;
+    page: {
+        path: string;
+    };
+    prepare: readonly Action[];
+    ready: readonly Expectation[];
+    capture: NonNullable<Recipe['capture']> | Record<string, never>;
+    browser: BrowserStatePatch;
+    safeVariables: JsonObject;
+}
+interface CaptureRequest {
+    job: ResolvedCaptureJob;
+    captureKey: string;
+}
+interface BrowserDriver extends ExtensionInfo {
+    describeEnvironment(): Promise<BrowserEnvironment>;
+    open(options: DriverRunOptions): Promise<BrowserRun>;
+}
+interface BrowserRun {
+    capture(request: CaptureRequest): Promise<CaptureResult>;
+    close(): Promise<void>;
+}
+interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface SceneTarget {
+    rect: Rect;
+    visible: boolean;
+    borderRadius?: number;
+}
+interface SceneViewport extends Viewport {
+    pixelRatio: number;
+    scrollX: number;
+    scrollY: number;
+}
+interface SceneBackground {
+    /**
+     * The image is already cropped to `frame`. Its dimensions are physical
+     * pixels; frame and target geometry use CSS pixels.
+     */
+    file: string;
+    width: number;
+    height: number;
+    format: 'png';
+    sha256: string;
+}
+interface CapturedScene {
+    version: 1;
+    captureKey: string;
+    recipeId: string;
+    variantKey: string;
+    variants: Readonly<Record<string, VariantValue>>;
+    frame: Rect;
+    viewport: SceneViewport;
+    targets: Readonly<Record<string, SceneTarget>>;
+    locale: string;
+    direction: 'ltr' | 'rtl';
+    theme?: string;
+    safeVariables: JsonObject;
+    background: SceneBackground;
+    environment: BrowserEnvironment;
+    sanitized: true;
+}
+interface CaptureResult {
+    scene: CapturedScene;
+    background: Uint8Array;
+}
+interface ResolvedAnnotation {
+    definition: Annotation;
+    text?: string;
+}
+type OutputFormat = 'png' | 'webp';
+interface CompositionOutput {
+    formats: readonly OutputFormat[];
+    quality?: number;
+    width?: number;
+    height?: number;
+}
+interface CompositionRequest {
+    scene: CapturedScene;
+    background: Uint8Array;
+    annotations: readonly ResolvedAnnotation[];
+    output: CompositionOutput;
+    theme?: string;
+}
+interface RenderedAsset {
+    format: OutputFormat;
+    mimeType: 'image/png' | 'image/webp';
+    bytes: Uint8Array;
+    width: number;
+    height: number;
+}
+interface AnnotationRenderer extends ExtensionInfo {
+    open(): Promise<RendererRun>;
+}
+interface RendererRun {
+    render(request: CompositionRequest): Promise<readonly RenderedAsset[]>;
+    close(): Promise<void>;
+}
+interface MatrixDefinition {
+    dimensions: Readonly<Record<string, readonly VariantValue[]>>;
+    include?: readonly Readonly<Record<string, VariantValue>>[];
+    exclude?: readonly Readonly<Record<string, VariantValue>>[];
+}
+interface VariantRow {
+    key: string;
+    values: Readonly<Record<string, VariantValue>>;
+}
+interface CaptureIntent {
+    recipeId: string;
+    profile: string;
+    serverUrl: string;
+    targetAttribute: `data-${string}`;
+    variants: Readonly<Record<string, VariantValue>>;
+    page: Recipe['page'];
+    scenario?: Recipe['scenario'];
+    prepare?: Recipe['prepare'];
+    ready?: Recipe['ready'];
+    capture?: Recipe['capture'];
+    profileConfig: CaptureProfile;
+    scenarioVersion?: string;
+    datasetRevision?: string;
+    dimensionVersions: Readonly<Record<string, string>>;
+    driver: Pick<BrowserDriver, 'name' | 'version'>;
+    translationVersion?: string;
+}
+interface CompositionIntent {
+    sceneHash: string;
+    annotations?: Recipe['annotations'];
+    accessibility: Recipe['accessibility'];
+    output?: Recipe['output'];
+    renderer: Pick<AnnotationRenderer, 'name' | 'version'>;
+    translationVersion?: string;
+}
+interface PlannedJob {
+    key: string;
+    recipeId: string;
+    recipeFile: string;
+    profile: string;
+    variantKey: string;
+    variants: Readonly<Record<string, VariantValue>>;
+    captureKey: string;
+    captureIntent: CaptureIntent;
+    compositionIntent: Omit<CompositionIntent, 'sceneHash'>;
+    recipe: Recipe;
+}
+interface RecipeSource {
+    file: string;
+    recipe: Recipe;
+}
+interface Plan {
+    jobs: readonly PlannedJob[];
+    recipes: readonly RecipeSource[];
+}
+declare function defineConfig<const TConfig extends GuideShotConfig>(config: TConfig): TConfig;
+declare function defineDimension<const TValue extends VariantValue, const TDefinition extends DimensionDefinition<TValue>>(definition: TDefinition): TDefinition;
+declare function defineScenario<const TInput extends JsonObject, const TDefinition extends ScenarioDefinition<TInput>>(definition: TDefinition): TDefinition;
+
+declare const DIAGNOSTIC_CODES: readonly ["RECIPE_SCHEMA_INVALID", "EXTENSION_NOT_REGISTERED", "VARIABLE_UNRESOLVED", "SERVER_NOT_READY", "ORIGIN_NOT_ALLOWED", "SCENARIO_FAILED", "NAVIGATION_FAILED", "TARGET_NOT_FOUND", "TARGET_NOT_UNIQUE", "TARGET_NOT_VISIBLE", "EXPECTATION_FAILED", "LAYOUT_UNSTABLE", "ANNOTATION_LAYOUT_FAILED", "PRIVACY_POLICY_FAILED", "CAPTURE_FAILED", "COMPOSITION_FAILED", "OUTPUT_COLLISION", "MANIFEST_INVALID", "OUTPUT_STALE"];
+type DiagnosticCode = (typeof DIAGNOSTIC_CODES)[number];
+type DiagnosticSeverity = 'error' | 'warning';
+interface DiagnosticLocation {
+    file?: string;
+    path?: string;
+    line?: number;
+    column?: number;
+}
+interface Diagnostic {
+    code: DiagnosticCode;
+    severity: DiagnosticSeverity;
+    message: string;
+    hint?: string;
+    recipeId?: string;
+    jobKey?: string;
+    location?: DiagnosticLocation;
+    details?: JsonObject;
+}
+interface GuideShotErrorOptions {
+    hint?: string;
+    recipeId?: string;
+    jobKey?: string;
+    location?: DiagnosticLocation;
+    details?: JsonObject;
+    cause?: unknown;
+}
+declare class GuideShotError extends Error {
+    readonly name = "GuideShotError";
+    readonly code: DiagnosticCode;
+    readonly hint: string | undefined;
+    readonly recipeId: string | undefined;
+    readonly jobKey: string | undefined;
+    readonly location: DiagnosticLocation | undefined;
+    readonly details: JsonObject | undefined;
+    constructor(code: DiagnosticCode, message: string, options?: GuideShotErrorOptions);
+    toDiagnostic(): Diagnostic;
+}
+declare function isGuideShotError(error: unknown): error is GuideShotError;
+declare function diagnosticFromUnknown(error: unknown, fallbackCode: DiagnosticCode): Diagnostic;
+
+declare function discoverRecipes(config: Pick<GuideShotConfig, 'recipes'>, projectRoot: string): Promise<RecipeSource[]>;
+declare function assertUniqueRecipeIds(sources: readonly RecipeSource[]): void;
+
+interface InterpolationContext {
+    scenario?: Readonly<JsonObject>;
+    variant: Readonly<Record<string, VariantValue>>;
+}
+declare function interpolate<T>(value: T, context: InterpolationContext): T;
+declare function interpolateString(value: string, context: InterpolationContext): JsonValue;
+
+interface ManifestAssetInput {
+    recipeId: string;
+    title?: string;
+    variantKey: string;
+    src: string;
+    width: number;
+    height: number;
+    format: OutputFormat$1;
+    hash: string;
+    alt: string;
+}
+declare function buildPublicManifest(assets: readonly ManifestAssetInput[]): PublicManifest;
+declare function createAssetPath(recipeId: string, variantKey: string, hash: string, format: OutputFormat$1): string;
+
+declare function expandMatrix(matrix?: MatrixDefinition): VariantRow[];
+declare function createVariantKey(variants: Readonly<Record<string, VariantValue>>): string;
+declare function matchesVariantFilter(variants: Readonly<Record<string, VariantValue>>, filter: Readonly<Record<string, VariantValue>>): boolean;
+
+interface PlanOptions {
+    ids?: readonly string[];
+    tags?: readonly string[];
+    variants?: Readonly<Record<string, VariantValue>>;
+}
+declare function planProject(config: GuideShotConfig, projectRoot: string, options?: PlanOptions): Promise<Plan>;
+declare function planRecipes(config: GuideShotConfig, sources: readonly RecipeSource[], options?: PlanOptions): Plan;
+declare function createJobCompositionHash(job: Pick<PlannedJob, 'compositionIntent'>, sceneHash: string): string;
+
+interface ResolveJobOptions {
+    baseUrl: URL;
+    signal?: AbortSignal;
+    fetch?: typeof globalThis.fetch;
+}
+interface ResolvedJob {
+    capture: ResolvedCaptureJob;
+    recipe: Recipe;
+    cleanup?: () => void | Promise<void>;
+}
+declare function resolveJob(planned: PlannedJob, config: GuideShotConfig, options: ResolveJobOptions): Promise<ResolvedJob>;
+declare function mergeBrowserState(...patches: readonly BrowserStatePatch[]): BrowserStatePatch;
+
+declare function assertAllowedOrigin(value: string | URL, allowedOrigins?: readonly string[]): URL;
+declare function resolvePageUrl(baseUrl: string | URL, pagePath: string): URL;
+interface SafeProjectPaths {
+    outputDir: string;
+    cacheDir: string;
+}
+declare function resolveSafeProjectPaths(projectRoot: string, outputDir: string, cacheDir: string): SafeProjectPaths;
+declare function resolveArtifactPath(outputDir: string, relativePath: string): string;
+declare function sanitizeFileSegment(value: string): string;
+
+interface ResolveTextContext {
+    locale: string;
+    variables: Readonly<JsonObject>;
+    variants: Readonly<Record<string, VariantValue>>;
+}
+declare function resolveLocalizedText(value: LocalizedText, provider: TranslationProvider | undefined, context: ResolveTextContext): Promise<string>;
+declare function resolveRecipeText(recipe: Recipe, provider: TranslationProvider | undefined, context: ResolveTextContext): Promise<Recipe>;
+declare function resolvedAnnotations(recipe: Recipe): ResolvedAnnotation[];
+declare function resolvedAlt(recipe: Recipe): string;
+
+interface ParseRecipeOptions {
+    file?: string;
+    format?: 'json' | 'jsonc';
+}
+declare function parseRecipe(source: string, options?: ParseRecipeOptions): Recipe;
+declare function validateRecipe(value: unknown, file?: string): Recipe;
+declare function validateManifest(value: unknown, file?: string): PublicManifest;
+declare function validateConfig(config: GuideShotConfig): void;
+declare function validateRecipeSemantics(source: RecipeSource, config: GuideShotConfig): void;
+declare function defaultProfileName(config: GuideShotConfig): string;
+
+export { type AnnotationRenderer, type BrowserCookie, type BrowserDriver, type BrowserEnvironment, type BrowserRun, type BrowserStatePatch, type CaptureIntent, type CaptureProfile, type CaptureRequest, type CaptureResult, type CapturedScene, type CompositionIntent, type CompositionOutput, type CompositionRequest, DIAGNOSTIC_CODES, type Diagnostic, type DiagnosticCode, type DiagnosticLocation, type DiagnosticSeverity, type DimensionDefinition, type DimensionResolveContext, type DriverRunOptions, type ExtensionInfo, type GuideShotConfig, GuideShotError, type GuideShotErrorOptions, type InterpolationContext, type LocalStorageState, type ManifestAssetInput, type MatrixDefinition, type ParseRecipeOptions, type Plan, type PlanOptions, type PlannedJob, type RecipeSource, type Rect, type RenderedAsset, type RendererRun, type ResolveJobOptions, type ResolveTextContext, type ResolvedAnnotation, type ResolvedCaptureJob, type ResolvedJob, type SafeProjectPaths, type SafetyConfig, type ScenarioContext, type ScenarioDefinition, type ScenarioResult, type SceneBackground, type SceneTarget, type SceneViewport, type ServerConfig, type TranslationContext, type TranslationProvider, type VariantRow, type Viewport, assertAllowedOrigin, assertUniqueRecipeIds, buildPublicManifest, canonicalSerialize, createAssetPath, createCaptureHash, createCompositionHash, createJobCompositionHash, createVariantKey, defaultProfileName, defineConfig, defineDimension, defineScenario, diagnosticFromUnknown, discoverRecipes, expandMatrix, hashCanonical, interpolate, interpolateString, isGuideShotError, matchesVariantFilter, mergeBrowserState, parseRecipe, planProject, planRecipes, resolveArtifactPath, resolveJob, resolveLocalizedText, resolvePageUrl, resolveRecipeText, resolveSafeProjectPaths, resolvedAlt, resolvedAnnotations, sanitizeFileSegment, sha256, validateConfig, validateManifest, validateRecipe, validateRecipeSemantics };