@industry-theme/file-city-panel 0.5.53 → 0.5.54

package/dist/types/Scope.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Scope / namespace / event records.
+ *
+ * In-memory model that mirrors the on-disk `.scopes.canvas` schema closely
+ * but flattens it into a tree the UI can navigate without touching JSON
+ * Canvas positioning details for reads.
+ *
+ * This package owns the type. electron-app's
+ * `services/scope-manager/types.ts` should swap to importing from here in
+ * the same migration as SequenceDiagram. See
+ * `docs/FILE_CITY_EXPLORER_PORT.md`.
+ *
+ * `ProjectArea` and `AuxiliaryManifest` are NOT defined here — those live
+ * upstream in `@principal-ai/principal-view-core` (>=0.27.0).
+ */
+export interface NodePosition {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface EventAttributeSchema {
+    type: string;
+    required?: boolean;
+    description?: string;
+}
+export interface EventRecord {
+    name: string;
+    severity?: 'INFO' | 'WARN' | 'ERROR';
+    description?: string;
+    attributes?: Record<string, EventAttributeSchema>;
+}
+export interface NamespaceRecord {
+    /** Namespace key (e.g. `"filetree"`). Unique within a scope. */
+    name: string;
+    description: string;
+    paths: string[];
+    events: EventRecord[];
+    /** Preserved canvas position so round-trips don't reflow the diagram. */
+    position?: NodePosition;
+    /** Hex color attached to the canvas node, if any. */
+    color?: string;
+    /** Stable canvas node id, preserved across writes. */
+    nodeId?: string;
+}
+export interface ScopeRecord {
+    /** Dotted scope name (e.g. `"principal-view.cli"`). Identity. */
+    name: string;
+    description?: string;
+    paths: string[];
+    /** Hex color from the `.scopes.canvas` node, if any. */
+    color?: string;
+    /** OTEL status from the `.scopes.canvas` node (`"draft"`, `"ready"`, etc.). */
+    status?: string;
+    /** Optional human-readable label override (defaults to `name`). */
+    label?: string;
+    namespaces: NamespaceRecord[];
+    /** Preserved canvas position for the otel-scope node. */
+    position?: NodePosition;
+    /** Stable canvas node id, preserved across writes. */
+    nodeId?: string;
+}
+export interface ScopeWorkspace {
+    scopes: ScopeRecord[];
+}
+export interface AddScopeInput {
+    name: string;
+    description?: string;
+    paths?: string[];
+    color?: string;
+    status?: string;
+    label?: string;
+}
+export interface AddNamespaceInput {
+    scopeName: string;
+    name: string;
+    description?: string;
+    paths?: string[];
+    color?: string;
+}
+export interface AddPathToNamespaceInput {
+    scopeName: string;
+    namespaceName: string;
+    path: string;
+}
+export interface AddEventInput {
+    scopeName: string;
+    namespaceName: string;
+    name: string;
+    severity?: 'INFO' | 'WARN' | 'ERROR';
+    description?: string;
+    attributes?: Record<string, EventAttributeSchema>;
+}
+//# sourceMappingURL=Scope.d.ts.map

package/dist/types/Scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Scope.d.ts","sourceRoot":"","sources":["../../src/types/Scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,YAAY;IAC3B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;CACnD;AAED,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,yDAAyD;IACzD,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,WAAW,EAAE,CAAC;CACvB;AAMD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;CACnD"}

package/dist/types/SequenceDiagram.d.ts

@@ -0,0 +1,306 @@
+/**
+ * Unified sequence-diagram types.
+ *
+ * Single source of truth for both `electron-app` and `web-ade`. Both
+ * historically maintained their own duplicated copies (electron's
+ * `FileCitySequenceAPI.ts`, web-ade's `lib/sequence-diagrams/types.ts`);
+ * this file replaces both. See `docs/FILE_CITY_EXPLORER_PORT.md` for the
+ * drift reconciliation that produced these shapes.
+ *
+ * Hardening choices (deviations from either historical copy):
+ * - `id`, `title`, `createdAt`, `updatedAt` are required on
+ *   `SequenceDiagramPayload`. Producers generate ids and timestamps;
+ *   storage layers reject payloads missing them.
+ * - `startLine` / `endLine` are required on `DiffSnippet` (matching
+ *   `SliceSnippet`).
+ * - `author` is required on notes; hosts identify the author at write
+ *   time (e.g. session user, agent name, or a system label).
+ * - `BaseSequenceDiagramIndexEntry.title` and `summaryPreview` are
+ *   required (empty string when there is no summary). UIs drop their
+ *   "missing" fallbacks; hosts derive defaults at index time.
+ */
+import type { SequenceEvent, SequenceEdge } from '@principal-ai/principal-view-react';
+export type { SequenceEvent, SequenceEdge };
+/**
+ * Slice snippet — single-file window over `event.sourcePath`.
+ *
+ * `kind` is optional for back-compat with producers that pre-date the
+ * discriminated union. Missing `kind` is treated as `'slice'`. New
+ * producers should always set it.
+ */
+export interface SliceSnippet {
+    kind?: 'slice';
+    /** First line of the snippet (1-based, inclusive). */
+    startLine: number;
+    /** Last line of the snippet (1-based, inclusive). */
+    endLine: number;
+    /** Line to highlight as the focus point; defaults to `startLine`. */
+    focusLine?: number;
+    /** Lines of context above/below the snippet; defaults to 2. */
+    contextLines?: number;
+}
+/**
+ * Diff snippet — before/after view inline. Used by code-review walkthroughs
+ * where each event represents a change region in a PR.
+ */
+export interface DiffSnippet {
+    kind: 'diff';
+    /** Pre-change file contents (full file or a pre-sliced window). */
+    oldContents: string;
+    /**
+     * Post-change file contents. When omitted, the renderer reads the current
+     * contents at `event.sourcePath` and diffs against `oldContents`.
+     */
+    newContents?: string;
+    /**
+     * Snippet window (1-based, inclusive) applied to both sides before
+     * diffing. Producers must set this — derive from contents length when
+     * the snippet covers the whole file.
+     */
+    startLine: number;
+    /** 1-based, inclusive. */
+    endLine: number;
+    /** Line in the post-change window to call out (1-based). */
+    focusLine?: number;
+    /** Lines of unchanged context kept around the window; defaults to 2. */
+    contextLines?: number;
+    /** Pierre rendering style. Defaults to `'unified'`. */
+    diffStyle?: 'unified' | 'split';
+    /** Syntax-highlighting hint (e.g. `'typescript'`, `'python'`). */
+    language?: string;
+    /**
+     * Opt-in hydration from GitHub at view time. No producer sets this today;
+     * declared so the schema is forward-compatible.
+     */
+    gitRef?: {
+        sha: string;
+        path: string;
+        branch?: string;
+    };
+}
+export type SequenceEventSnippet = SliceSnippet | DiffSnippet;
+/**
+ * Sequence event used by File City. Adds an optional snippet reference and
+ * human-readable description on top of the upstream `SequenceEvent` shape.
+ */
+export type FileCitySequenceEventDef = SequenceEvent & {
+    snippet?: SequenceEventSnippet;
+    /**
+     * Human-readable description of the change/event. Surfaced in the
+     * left-edge explainer overlay when the event is selected — useful for
+     * code-review walkthroughs where each event needs a "why" alongside the
+     * snippet.
+     */
+    description?: string;
+};
+export interface SequenceLayoutOptions {
+    /**
+     * Resolved namespaces in left-to-right order. Listed lanes are placed
+     * first; any unlisted lanes (including ones that materialize after a
+     * drill-down) fall back to first-event order behind them. Unknown
+     * entries are ignored, so callers can safely list namespaces that may
+     * not be present in every dataset.
+     *
+     * Without this option, lane order follows the order events first appear
+     * in `payload.events`.
+     */
+    laneOrder?: string[];
+}
+/**
+ * One disjoint line range covered by a slice anchor. Notes can cover
+ * multiple ranges (e.g. a comment that spans two related code blocks);
+ * each range carries its own re-anchor fingerprints so the note can be
+ * re-located even if intervening lines move.
+ */
+export interface SliceRange {
+    /** 1-based absolute line in the source file (inclusive). */
+    startLine: number;
+    /** 1-based absolute line (inclusive). For single-line ranges, equals `startLine`. */
+    endLine: number;
+    /** `startLine`'s text at creation time — re-anchor fingerprint. */
+    startLineText: string;
+    /** `endLine`'s text at creation time. Equals `startLineText` for single-line ranges. */
+    endLineText: string;
+}
+export interface SnippetSliceAnchor {
+    kind: 'slice';
+    /**
+     * One or more disjoint ranges this note covers. Multi-range notes show
+     * one indicator pill per range start; the side panel renders one
+     * thread.
+     */
+    ranges: SliceRange[];
+}
+export interface SnippetDiffAnchor {
+    kind: 'diff';
+    side: 'deletions' | 'additions';
+    lineNumber: number;
+}
+/**
+ * Note attached to a snippet line. Lives on `payload.notes` so persistence
+ * and broadcast piggyback on the existing payload path. Only the renderer
+ * or host can mutate notes — external HTTP POSTs of payloads must strip
+ * this field during validation.
+ */
+export interface SequenceSnippetNote {
+    id: string;
+    kind: 'snippet';
+    scope: {
+        eventId: string;
+    };
+    anchor: SnippetSliceAnchor | SnippetDiffAnchor;
+    body: string;
+    /**
+     * Required. Hosts identify the author at write time — current user,
+     * agent name, or a system label like `'anonymous'`. Display code drops
+     * its `if (note.author)` guard.
+     */
+    author: string;
+    /** ISO 8601. */
+    createdAt: string;
+    /** ISO 8601 — equal to `createdAt` until first edit. */
+    updatedAt: string;
+}
+/**
+ * Markdown notes anchor to a quoted span using the W3C text-quote
+ * selector (matches themed-markdown's `Annotation.anchor` shape).
+ */
+export interface MarkdownTextQuoteAnchor {
+    kind: 'text-quote';
+    exact: string;
+    prefix?: string;
+    suffix?: string;
+}
+/**
+ * Where in the markdown overlay the note is anchored. The overlay swaps
+ * between an event's `description` and the payload's `summary`, so we tag
+ * which surface the note belongs to.
+ */
+export type MarkdownNoteScope = {
+    kind: 'description';
+    eventId: string;
+} | {
+    kind: 'summary';
+};
+/**
+ * Note attached to a markdown selection in the left-edge sequence-diagram
+ * overlay. Same persistence story as `SequenceSnippetNote` — lives on
+ * `payload.notes`, mutated only via host actions, stripped from external
+ * HTTP payloads during validation.
+ */
+export interface SequenceMarkdownNote {
+    id: string;
+    kind: 'markdown';
+    scope: MarkdownNoteScope;
+    anchor: MarkdownTextQuoteAnchor;
+    body: string;
+    /** Required — see hardening note on `SequenceSnippetNote.author`. */
+    author: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Discriminated union of all note variants. */
+export type SequenceNote = SequenceSnippetNote | SequenceMarkdownNote;
+/**
+ * Payload accepted by note-creation endpoints. Server fills `id`,
+ * `createdAt`, `updatedAt`. Discriminated on `kind` so handlers can
+ * narrow without conditional fields.
+ */
+export type SequenceNoteDraft = Omit<SequenceSnippetNote, 'id' | 'createdAt' | 'updatedAt'> | Omit<SequenceMarkdownNote, 'id' | 'createdAt' | 'updatedAt'>;
+/**
+ * Unified sequence-diagram payload.
+ *
+ * Producers build it with `id`/timestamps already set; storage layers
+ * reject payloads missing required fields. The `repositoryPath` field is
+ * only meaningful on the producer side (electron filters open File City
+ * panels by it) — web hosts can leave it unset.
+ */
+export interface SequenceDiagramPayload {
+    /**
+     * Stable id. Producers generate it (e.g. `crypto.randomUUID()`);
+     * storage layers reject payloads missing it.
+     */
+    id: string;
+    /**
+     * Title shown in the drawer header. Hosts derive a default
+     * (e.g. first event name or `"Untitled flow"`) at construction time.
+     */
+    title: string;
+    /**
+     * Free-form categorization. Used by web-ade's share flow to tag
+     * payloads (e.g. `'pr-walkthrough'`, `'incident'`). Electron ignores it.
+     */
+    kind?: string;
+    /**
+     * Producer-side filesystem path; renderers filter by this so a payload
+     * targets only the matching File City panel when several are open.
+     * Web hosts can leave this unset.
+     */
+    repositoryPath?: string;
+    /**
+     * Markdown summary of the whole flow. Surfaced in the left-edge
+     * overlay when no event is selected; per-event `description` takes
+     * over once the user picks an event.
+     */
+    summary?: string;
+    /** Events in display order. */
+    events: FileCitySequenceEventDef[];
+    /** Edges between events. */
+    edges?: SequenceEdge[];
+    /** Renderer layout knobs (lane ordering, etc.). */
+    layoutOptions?: SequenceLayoutOptions;
+    /**
+     * ISO 8601 — set at payload creation. Storage layers reject payloads
+     * missing it.
+     */
+    createdAt: string;
+    /**
+     * ISO 8601 — equals `createdAt` until first edit, then bumped on
+     * every persist.
+     */
+    updatedAt: string;
+    /**
+     * User-authored notes anchored to events. Mutated only via host
+     * endpoints; external HTTP POSTs must strip this field during
+     * validation.
+     */
+    notes?: SequenceNote[];
+}
+/**
+ * Manifest entry that summarizes a payload without loading it. Only the
+ * fields any picker UI actually needs.
+ *
+ * Each host extends this with storage-specific fields (filesystem path /
+ * S3 ownership / GitHub repo id / etc.) on its own side. Do NOT add
+ * storage-coupled fields here — they're host-private by design, and
+ * adding them here would re-couple the UI to a particular storage layer.
+ *
+ * Picker UIs in this package type their props against
+ * `BaseSequenceDiagramIndexEntry`; each host's storage layer extends
+ * with its own fields and assigns into the base via TypeScript
+ * covariance.
+ */
+export interface BaseSequenceDiagramIndexEntry {
+    id: string;
+    /**
+     * Required. Hosts must provide a non-empty string — derive from the
+     * payload (e.g. first event name) or fall back to a placeholder like
+     * `"Untitled flow"` at index time. Picker UIs no longer carry the
+     * fallback.
+     */
+    title: string;
+    /**
+     * Required. First ~200 chars of `payload.summary`, or empty string
+     * when the payload has no summary. Empty-but-present means picker UIs
+     * can drop their `if (entry.summaryPreview)` guard.
+     */
+    summaryPreview: string;
+    eventCount: number;
+    hasDiffSnippets: boolean;
+    /** ISO 8601. */
+    createdAt: string;
+    /** ISO 8601. */
+    updatedAt: string;
+    sizeBytes: number;
+}
+//# sourceMappingURL=SequenceDiagram.d.ts.map

package/dist/types/SequenceDiagram.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SequenceDiagram.d.ts","sourceRoot":"","sources":["../../src/types/SequenceDiagram.ts"],"names":[],"mappings":"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"}

package/dist/types/TextToSpeech.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Text-to-Speech Adapter Types
+ *
+ * These types define the interface for TTS functionality in tour players.
+ * The host application provides a TTS adapter implementation that handles
+ * audio generation, caching, and playback.
+ */
+/**
+ * Audio event types
+ */
+export type TTSEvent = 'ended' | 'error' | 'playing' | 'paused' | 'loading';
+/**
+ * Current state of the TTS system
+ */
+export interface TTSState {
+    /** Whether audio is currently being loaded/generated */
+    isLoading: boolean;
+    /** Whether audio is currently playing */
+    isPlaying: boolean;
+    /** Whether audio is paused */
+    isPaused: boolean;
+    /** Current error, if any */
+    error: Error | null;
+    /** Playback progress (0-100) */
+    progress?: number;
+    /** Total duration in seconds */
+    duration?: number;
+    /** Current playback time in seconds */
+    currentTime?: number;
+}
+/**
+ * Options for TTS generation and playback
+ */
+export interface TTSOptions {
+    /** Voice identifier (e.g., ElevenLabs voice ID) */
+    voice?: string;
+    /** Speech speed multiplier (0.5 - 2.0) */
+    speed?: number;
+    /** Pitch adjustment (if supported by TTS provider) */
+    pitch?: number;
+}
+/**
+ * Context information for fetching tour audio
+ * This is used to identify the tour file in version control
+ */
+export interface TourAudioContext {
+    /** Repository owner (e.g., "anthropics") */
+    owner: string;
+    /** Repository name (e.g., "web-ade") */
+    repo: string;
+    /** Path to tour file in repo (e.g., "docs/tours/intro.tour.json") */
+    path: string;
+    /** Git commit SHA to ensure cache invalidation on changes (optional for cacheOnly mode) */
+    commitSha?: string;
+    /** When true, only fetch cached audio - don't trigger generation */
+    cacheOnly?: boolean;
+}
+/**
+ * Text-to-Speech Adapter Interface
+ *
+ * Host applications implement this interface to provide TTS functionality.
+ * The adapter handles audio generation, caching (e.g., S3), and playback.
+ *
+ * Security: The adapter should NOT accept arbitrary text. Instead, it should
+ * fetch tour content from a trusted source (e.g., GitHub) using the context
+ * information provided.
+ */
+export interface TextToSpeechAdapter {
+    /**
+     * Fetch audio URLs for all steps in a tour
+     * This is called when the tour loads to ensure audio is available
+     *
+     * @param tourId - Unique identifier for the tour
+     * @param stepIds - Array of step IDs to fetch audio for
+     * @param context - Repository and file context
+     * @param options - Voice and playback options
+     * @returns Map of stepId -> audio URL
+     */
+    fetchTourAudio(tourId: string, stepIds: string[], context: TourAudioContext, options?: TTSOptions): Promise<Map<string, string>>;
+    /**
+     * Play audio for a specific step
+     *
+     * @param stepId - The step ID to play audio for
+     * @throws Error if audio URL not found (fetchTourAudio must be called first)
+     */
+    speak(stepId: string): Promise<void>;
+    /**
+     * Stop current audio playback and reset position
+     */
+    stop(): void;
+    /**
+     * Pause current audio playback (preserves position)
+     */
+    pause(): void;
+    /**
+     * Resume paused audio playback
+     */
+    resume(): void;
+    /**
+     * Current state of the TTS system
+     */
+    readonly state: TTSState;
+    /**
+     * Subscribe to TTS events
+     *
+     * @param event - Event type to listen for
+     * @param handler - Callback function
+     */
+    addEventListener(event: TTSEvent, handler: () => void): void;
+    /**
+     * Unsubscribe from TTS events
+     *
+     * @param event - Event type to stop listening for
+     * @param handler - Callback function to remove
+     */
+    removeEventListener(event: TTSEvent, handler: () => void): void;
+}
+//# sourceMappingURL=TextToSpeech.d.ts.map

package/dist/types/TextToSpeech.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TextToSpeech.d.ts","sourceRoot":"","sources":["../../src/types/TextToSpeech.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE5E;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,wDAAwD;IACxD,SAAS,EAAE,OAAO,CAAC;IAEnB,yCAAyC;IACzC,SAAS,EAAE,OAAO,CAAC;IAEnB,8BAA8B;IAC9B,QAAQ,EAAE,OAAO,CAAC;IAElB,4BAA4B;IAC5B,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAEpB,gCAAgC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,gCAAgC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,uCAAuC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IAEd,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IAEb,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IAEb,2FAA2F;IAC3F,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,oEAAoE;IACpE,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;OASG;IACH,cAAc,CACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,EAAE,gBAAgB,EACzB,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAEhC;;;;;OAKG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErC;;OAEG;IACH,IAAI,IAAI,IAAI,CAAC;IAEb;;OAEG;IACH,KAAK,IAAI,IAAI,CAAC;IAEd;;OAEG;IACH,MAAM,IAAI,IAAI,CAAC;IAEf;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IAEzB;;;;;OAKG;IACH,gBAAgB,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAE7D;;;;;OAKG;IACH,mBAAmB,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CACjE"}

package/dist/types/TourExtensions.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Tour Image Resolution Utilities
+ *
+ * Utilities for resolving relative image paths to full URLs for tour cover images.
+ * The coverImage field is now natively supported in IntroductionTour and IntroductionTourStep
+ * from @principal-ai/file-city-builder v0.4.2+
+ */
+/**
+ * Repository context for resolving relative image paths
+ * Reuses the structure from TourAudioContext
+ */
+export interface ImageResolutionContext {
+    /** Repository owner (e.g., "anthropics") */
+    owner: string;
+    /** Repository name (e.g., "web-ade") */
+    repo: string;
+    /** Git commit SHA or branch name for consistent URLs */
+    ref: string;
+}
+/**
+ * Resolve a relative image path to a full GitHub raw URL
+ *
+ * @param relativePath - Path relative to repo root (e.g., "assets/cover.png")
+ * @param context - Repository context
+ * @returns Full URL to the image
+ */
+export declare function resolveImageUrl(relativePath: string, context: ImageResolutionContext): string;
+//# sourceMappingURL=TourExtensions.d.ts.map

package/dist/types/TourExtensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TourExtensions.d.ts","sourceRoot":"","sources":["../../src/types/TourExtensions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IAEd,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IAEb,wDAAwD;IACxD,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,sBAAsB,GAC9B,MAAM,CAWR"}