@devcabs/folio-engine 0.0.0-stage → 0.1.1

package/dist/services/canvasLayoutService.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Folio Engine - Hybrid Local-First Storage & Layout Synchronization Service
+ * Location: src/services/canvasLayoutService.ts
+ * Specification: docs/tasks/task8_2_storage_and_sync_service.md
+ * Aligned with: docs/00_WORKFLOW.md, docs/03_ARCHITECTURE.md, docs/07_CODING_STANDARDS.md
+ *
+ * Implements:
+ * 1. Synchronous Local-First Storage (`localStorage` under `folio_canvas_${nodeId}`).
+ * 2. Cross-Component Event Bus (`engine-canvas-change`).
+ * 3. Immutable tree operations with strict section auto-numbering.
+ * 4. Resilient schema recovery and optional cloud persistence bridge.
+ */
+import type { CanvasElement, CanvasLeafElement, SectionElement, SubsectionElement, NodeCanvasDocument } from '../types/canvas';
+export declare const getCanvasLiveStoragePrefix: (ns?: string) => string;
+export declare const CANVAS_LIVE_STORAGE_PREFIX: string;
+export declare const getCanvasDraftStoragePrefix: (ns?: string) => string;
+export declare const CANVAS_DRAFT_STORAGE_PREFIX: string;
+export declare const getCanvasLegacyStoragePrefix: (ns?: string) => string;
+export declare const CANVAS_LEGACY_STORAGE_PREFIX: string;
+export declare const CANVAS_STORAGE_PREFIX: string;
+export declare const EVENT_LIVE_CANVAS_CHANGE = "engine-live-canvas-change";
+export declare const EVENT_DRAFT_CANVAS_CHANGE = "engine-draft-canvas-change";
+export declare const CANVAS_SCHEMA_VERSION = 2;
+export declare const NODE_IDS: readonly ["access", "equity", "quality", "resiliency", "governance"];
+export type NodeId = (typeof NODE_IDS)[number];
+export interface SaveCanvasOptions {
+    silent?: boolean;
+}
+export interface CanvasChangeEventDetail {
+    nodeId: string;
+    document: NodeCanvasDocument;
+}
+export interface SaveResult {
+    ok: boolean;
+    error?: 'quota' | 'unknown';
+    document: NodeCanvasDocument;
+}
+export interface CanvasLayoutService {
+    getNodeCanvas(nodeId: string, isDevMode?: boolean): NodeCanvasDocument;
+    saveNodeCanvas(doc: NodeCanvasDocument, isDevMode?: boolean): SaveResult;
+    resetNodeCanvas(nodeId: string, isDevMode?: boolean): NodeCanvasDocument;
+    subscribeToCanvasChange(nodeId: string, callback: (doc: NodeCanvasDocument) => void, isDevMode?: boolean): () => void;
+    deployNodeCanvasToCloud(nodeId: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+}
+/**
+ * Derives the canonical live localStorage key for a specific node.
+ */
+export declare function getCanvasStorageKey(nodeId: string): string;
+/**
+ * Derives the draft localStorage key for a specific node.
+ */
+export declare function getDraftCanvasStorageKey(nodeId: string): string;
+/**
+ * Seamlessly migrates legacy folio_canvas_* and folio_content_overrides keys to folio_live_*.
+ * Guarantees zero data loss for existing tenant configurations upon system update.
+ */
+export declare function migrateLegacyStorageKeys(): void;
+/**
+ * Folds ContentDB overrides into a single NodeCanvasDocument.
+ */
+export declare function foldCanvasOverridesIntoDocument(doc: NodeCanvasDocument, overrides: Record<string, string>): {
+    modified: boolean;
+    consumedKeys: string[];
+};
+/**
+ * One-time idempotent migration that merges non-empty ContentDB overrides into the Canvas AST.
+ * Deletes consumed ContentDB keys to prevent legacy overrides from lingering.
+ */
+export declare function migrateCanvasOverridesIntoAst(channel: 'live' | 'draft'): void;
+/**
+ * Enforces sequential section numbering ("01", "02", "03"...) immutably.
+ */
+export declare function renumberSections(sections: SectionElement[]): SectionElement[];
+/**
+ * Inserts a section into the document tree with automatic renumbering.
+ */
+export declare function insertSection(doc: NodeCanvasDocument, section: SectionElement, targetIndex?: number): NodeCanvasDocument;
+/**
+ * Inserts a subsection container within a targeted section.
+ */
+export declare function insertSubsection(doc: NodeCanvasDocument, sectionId: string, subsection: SubsectionElement, targetIndex?: number): NodeCanvasDocument;
+/**
+ * Inserts a leaf element (text, photo, or chart) into a section or nested subsection.
+ */
+export declare function insertLeafElement(doc: NodeCanvasDocument, sectionId: string, element: CanvasLeafElement, targetIndex?: number, subsectionId?: string): NodeCanvasDocument;
+/**
+ * Moves an item up or down within its current container hierarchy.
+ */
+/**
+ * Moves an item up or down, seamlessly traversing section boundaries when reaching the top or bottom of a section.
+ */
+export declare function moveCanvasItem(doc: NodeCanvasDocument, itemId: string, direction: 'up' | 'down', parentId?: string): NodeCanvasDocument;
+/**
+ * Relocates any canvas element (section, subsection, or leaf) from anywhere in the document
+ * to a new container and target index (powers cross-section drag-and-drop).
+ */
+export declare function relocateCanvasItem(doc: NodeCanvasDocument, sourceItemId: string, targetContainerId: string, targetIndex?: number): NodeCanvasDocument;
+/**
+ * Removes an item and all its nested children from the canvas document tree.
+ */
+export declare function removeCanvasItem(doc: NodeCanvasDocument, itemId: string, parentId?: string): NodeCanvasDocument;
+/**
+ * Immutably updates attributes of any canvas element by ID.
+ */
+export declare function updateCanvasItem<T extends CanvasElement>(doc: NodeCanvasDocument, itemId: string, updates: Partial<T>): NodeCanvasDocument;
+export interface CanvasItemLocation {
+    item: CanvasElement;
+    kind: 'section' | 'subsection' | 'leaf';
+    index: number;
+    sectionId: string;
+    subsectionId?: string;
+}
+/**
+ * Finds any item within the canvas document and returns its structural location and container.
+ */
+export declare function findCanvasItemLocation(doc: NodeCanvasDocument, itemId: string): CanvasItemLocation | null;
+/**
+ * Synchronous retrieval of a node canvas document strictly from the live/published channel.
+ */
+export declare function getLiveNodeCanvas(nodeId: string): NodeCanvasDocument;
+/**
+ * Persists a canvas document strictly to the live/published channel.
+ */
+export declare function saveLiveNodeCanvas(doc: NodeCanvasDocument, options?: SaveCanvasOptions): SaveResult;
+/**
+ * Synchronous local-first retrieval of a node canvas document.
+ * Reads from draft sandbox if Developer Mode is active (isDevMode === true);
+ * otherwise strictly and unconditionally from the canonical live published channel.
+ */
+export declare function getNodeCanvas(nodeId: string, isDevMode?: boolean): NodeCanvasDocument;
+/**
+ * Persists canvas document to storage (draft or live) and broadcasts change via scoped CustomEvent.
+ */
+export declare function saveNodeCanvas(doc: NodeCanvasDocument, isDevMode?: boolean, options?: SaveCanvasOptions): SaveResult;
+/**
+ * Dispatches an aggregate canvas change event with nodeId: '*' to notify all node consumers at once.
+ */
+export declare function dispatchAggregateCanvasChange(isDevMode?: boolean): void;
+/**
+ * Resets storage for a node back to factory defaults and broadcasts change via scoped CustomEvent.
+ */
+export declare function resetNodeCanvas(nodeId: string, isDevMode?: boolean): NodeCanvasDocument;
+/**
+ * Subscribes a listener to canvas change events strictly scoped by channel.
+ * Public views (isDevMode === false) never receive uncommitted draft events.
+ */
+export declare function subscribeToCanvasChange(nodeId: string, callback: (doc: NodeCanvasDocument) => void, isDevMode?: boolean): () => void;
+/**
+ * Deploys the active canvas document to cloud storage (Supabase).
+ */
+export declare function deployNodeCanvasToCloud(nodeId: string): Promise<{
+    success: boolean;
+    error?: string;
+}>;
+export declare const canvasLayoutService: CanvasLayoutService;

package/dist/services/chartSourceService.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Supabase Cloud Storage & Chart Source Persistence Service
+ * Folio Engine
+ * Document Reference: docs/tasks/task7_2_access_verification_sheets_api.md
+ *
+ * Implements:
+ * 1. PostgREST / Supabase persistence for live chart configurations.
+ * 2. Instant-paint client cache backed by localStorage.
+ * 3. Zero-leak data security enforcement (internal Google Sheet URLs are stripped
+ *    for public consumers).
+ * 4. Fault-tolerant offline and fallback handling.
+ */
+import type { SheetChartConfig } from '../types/chart';
+import type { NodeCode } from '../types/node';
+export declare const getChartSourcePrefix: (ns?: string) => string;
+export declare const LOCAL_STORAGE_PREFIX: string;
+export declare const getChartSourcesManifestKey: (ns?: string) => string;
+export declare const LOCAL_STORAGE_ALL_KEY: string;
+export declare const EVENT_CHART_SOURCE_CHANGE = "engine-chart-source-change";
+/**
+ * Helper to dispatch window events for live reactivity across chart components.
+ */
+export declare function notifyChartChange(chartId: string, config: SheetChartConfig): void;
+/**
+ * Publicly safe version of SheetChartConfig with private Google Sheet URL omitted.
+ */
+export type PublicChartConfig = Omit<SheetChartConfig, 'sheetUrl'>;
+export interface ChartSourceDbRow {
+    chart_id: string;
+    node_id: string;
+    sheet_url: string;
+    tab_name?: string | null;
+    sheet_gid?: string | null;
+    range?: string | null;
+    default_type?: string | null;
+    title_override?: string | null;
+    subtitle_override?: string | null;
+    unit_override?: string | null;
+    visual_config?: Record<string, unknown> | null;
+    cached_dataset?: (string | number | null)[][] | null;
+    updated_at?: string | null;
+    updated_by?: string | null;
+}
+import { getSupabaseConfig } from '../utils/supabase-config';
+export { getSupabaseConfig };
+/**
+ * Maps database record to typed client model.
+ */
+export declare function mapDbRowToChartConfig(row: ChartSourceDbRow): SheetChartConfig;
+/**
+ * Maps client model to database record payload.
+ */
+export declare function mapChartConfigToDbRow(config: SheetChartConfig): ChartSourceDbRow;
+/**
+ * Strips internal Google Sheet URL for public/client presentations (Zero-Leak Security).
+ */
+export declare function sanitizePublicChartConfig(config: SheetChartConfig): PublicChartConfig;
+/**
+ * Loads a cached chart configuration from memory or local storage.
+ */
+export declare function getCachedChartConfig(chartId: string): SheetChartConfig | null;
+/**
+ * Saves a chart configuration to memory and local storage.
+ * Returns true if stored locally (or in memory in non-browser environments).
+ */
+export declare function setCachedChartConfig(config: SheetChartConfig): boolean;
+/**
+ * Asynchronously fetches a chart configuration from Supabase or local cache.
+ */
+export declare function fetchChartConfig(chartId: string, options?: {
+    forceRefresh?: boolean;
+}): Promise<SheetChartConfig | null>;
+/**
+ * Fetches all chart configurations belonging to a specific node.
+ */
+export declare function fetchChartConfigsByNode(nodeId: NodeCode, _options?: {
+    forceRefresh?: boolean;
+}): Promise<SheetChartConfig[]>;
+/**
+ * Detailed outcome of persisting chart configuration across local and cloud stores.
+ */
+export interface SaveChartConfigResult {
+    /**
+     * Whether the configuration was persisted (at least locally).
+     */
+    success: boolean;
+    /**
+     * Whether the configuration was saved to local browser storage / memory cache.
+     */
+    savedLocally: boolean;
+    /**
+     * Whether the configuration was synced to Supabase cloud.
+     */
+    savedToCloud: boolean;
+    /**
+     * Diagnostic error explanation with specific cause.
+     */
+    error?: string;
+    /**
+     * Diagnostic error code (e.g. PGRST205, HTTP_404, AUTH_FORBIDDEN, NETWORK_ERROR, QUOTA_EXCEEDED).
+     */
+    errorCode?: string;
+    /**
+     * HTTP status code if rejected by remote server.
+     */
+    statusCode?: number;
+    /**
+     * Additional diagnostic details or server hints.
+     */
+    details?: string;
+}
+/**
+ * Persists chart configuration with granular diagnostics and variance reporting.
+ */
+export declare function saveChartConfigDetailed(config: SheetChartConfig, token?: string): Promise<SaveChartConfigResult>;
+/**
+ * Formats a high-variance, user-facing error message with diagnostic context.
+ */
+export declare function formatSaveErrorMessage(result: SaveChartConfigResult | Error | unknown, action?: 'save' | 'deploy'): string;
+/**
+ * Persists chart configuration to local cache and Supabase cloud.
+ * Maintained for backward compatibility.
+ */
+export declare function saveChartConfig(config: SheetChartConfig, token?: string): Promise<boolean>;
+/**
+ * Clears cached chart configurations.
+ */
+export declare function resetChartSourceCache(chartId?: string): void;

package/dist/services/devLockService.d.ts

@@ -0,0 +1,76 @@
+/**
+ * devLockService.ts
+ * Folio Engine: Developer Mode Database Session Lock & Race Prevention Service
+ * Task 9.1: docs/tasks/task9_1_dev_mode_database_session_lock.md
+ *
+ * Enforces strict single-coordinator exclusivity across the portal:
+ * 1. PostgREST / Supabase cloud persistence for live cross-device coordinator lock.
+ * 2. High-resilience localStorage multi-tab fallback with cross-tab storage events.
+ * 3. 30-second heartbeat renewal with 60-second crash recovery timeout.
+ * 4. Beacon-based immediate release on tab/window unload (navigator.sendBeacon / fetch keepalive).
+ */
+import type { DevSessionLock, DevLockStatusResponse } from '../types/developer';
+export declare const getDevLockStorageKey: (ns?: string) => string;
+export declare const DEV_LOCK_STORAGE_KEY: string;
+export declare const getDevSessionIdKey: (ns?: string) => string;
+export declare const DEV_SESSION_ID_KEY: string;
+export declare const HEARTBEAT_INTERVAL_MS = 30000;
+export declare const LOCK_EXPIRATION_MS = 60000;
+import { getSupabaseConfig, isTableAvailable, markTableMissing } from '../utils/supabase-config';
+export { getSupabaseConfig, isTableAvailable, markTableMissing };
+export declare const TAB_INSTANCE_ID: string;
+export declare function getSessionBroadcastChannel(): BroadcastChannel | null;
+/**
+ * Regenerates a unique browser tab session ID (used when a cloned tab is detected).
+ */
+export declare function regenerateSessionId(): string;
+/**
+ * Generates or retrieves a persistent browser tab session ID.
+ */
+export declare function getSessionId(): string;
+/**
+ * Reset memory session ID (primarily for test harness isolation).
+ */
+export declare function resetSessionIdForTesting(newId?: string): void;
+/**
+ * Evaluates whether an active lock has expired past the 60-second crash recovery window.
+ */
+export declare function isLockExpired(lock: DevSessionLock, now?: number): boolean;
+/**
+ * Read the local session lock state from persistent storage.
+ */
+export declare function getLocalLock(): DevSessionLock | null;
+/**
+ * Write the local session lock state to persistent storage.
+ */
+export declare function setLocalLock(lock: DevSessionLock | null): void;
+/**
+ * Query active lock status from Supabase cloud or local multi-tab cache.
+ */
+export declare function checkDevLockStatus(sessionId: string): Promise<DevLockStatusResponse>;
+/**
+ * Attempt to acquire the Developer Mode lock institutional-wide.
+ * Enforces atomic Compare-And-Swap (CAS) against Supabase cloud storage.
+ */
+export declare function acquireDevLock(sessionId: string, coordinatorLabel?: string): Promise<{
+    success: boolean;
+    lock?: DevSessionLock;
+    error?: string;
+}>;
+/**
+ * Renews the liveness timestamp for the active session.
+ * Rejects renewal if another session has claimed the cloud row.
+ */
+export declare function renewDevLockHeartbeat(sessionId: string): Promise<boolean>;
+/**
+ * Releases the Developer Mode lock cleanly.
+ */
+export declare function releaseDevLock(sessionId: string): Promise<boolean>;
+/**
+ * Dispatches an instant release beacon when tab/window unloads (beforeunload/pagehide).
+ */
+export declare function releaseDevLockBeacon(sessionId: string): void;
+/**
+ * Subscribes to cross-tab lock changes via storage events.
+ */
+export declare function subscribeToLockStorage(callback: (lock: DevSessionLock | null) => void): () => void;

package/dist/services/draftService.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Folio Engine - Draft Isolation & Cloud DB-Draft Service
+ * Location: src/services/draftService.ts
+ * Specification: docs/tasks/task11_2g_db_draft_and_blob_storage_pipeline.md
+ * Aligned with: docs/00_WORKFLOW.md, docs/03_ARCHITECTURE.md, docs/07_CODING_STANDARDS.md
+ *
+ * Implements:
+ * 1. Zero-localStorage in-memory draft sandbox for 60 FPS editing.
+ * 2. Active draft lifecycle & dirty change tracking (hasUnpublishedChanges).
+ * 3. Cloud-backed draft synchronization with Supabase engine_drafts table.
+ * 4. 1500ms debounced auto-sync with status events (saved, saving, error, offline).
+ * 5. Safe draft discard and multi-device continuation.
+ */
+import type { NodeCanvasDocument } from '../types/canvas';
+import type { CloudDraftData, CloudDraftSyncStatus, DraftSyncStatusEventDetail } from '../types/draft';
+export declare const getDraftCanvasPrefix: (ns?: string) => string;
+export declare const DRAFT_CANVAS_PREFIX: string;
+export declare const getDraftContentKey: (ns?: string) => string;
+export declare const DRAFT_CONTENT_KEY: string;
+export declare const getDraftActiveKey: (ns?: string) => string;
+export declare const DRAFT_ACTIVE_KEY: string;
+export declare const getDraftDirtyKey: (ns?: string) => string;
+export declare const DRAFT_DIRTY_KEY: string;
+export declare const EVENT_DRAFT_STATUS_CHANGE = "engine-draft-status-change";
+export declare const EVENT_CLOUD_DRAFT_SYNC_STATUS = "engine-cloud-draft-sync-status";
+export declare const AUTOSYNC_DEBOUNCE_MS = 1500;
+export interface DraftActiveMetadata {
+    baseId: string | null;
+    startedAt?: string;
+}
+export interface DraftStalenessCheck {
+    isStale: boolean;
+    baseId: string | null;
+    currentActiveId: string;
+}
+/**
+ * Returns the legacy draft canvas storage key for a specific node.
+ */
+export declare function getDraftCanvasKey(nodeId: string): string;
+/**
+ * Retrieves in-memory draft canvas for a node.
+ */
+export declare function getInMemoryDraftCanvas(nodeId: string): NodeCanvasDocument | null;
+/**
+ * Sets in-memory draft canvas for a node.
+ */
+export declare function setInMemoryDraftCanvas(nodeId: string, doc: NodeCanvasDocument): void;
+/**
+ * Whether Developer Mode draft sandbox is currently active.
+ */
+export declare function isDraftModeActive(): boolean;
+/**
+ * Retrieves the base snapshot ID that the current draft was cloned from.
+ */
+export declare function getDraftBaseId(): string | null;
+/**
+ * Checks whether the current draft is stale compared to the live active published snapshot.
+ */
+export declare function checkDraftStaleness(): DraftStalenessCheck;
+/**
+ * Boolean convenience helper to check if draft is stale.
+ */
+export declare function isDraftStale(): boolean;
+/**
+ * Activates or deactivates the draft sandbox mode.
+ */
+export declare function setDraftModeActive(active: boolean, baseId?: string | null): void;
+/**
+ * Checks whether the current draft has uncommitted changes.
+ */
+export declare function isDraftDirty(): boolean;
+/**
+ * Sets the draft dirty flag and dispatches draft change event.
+ */
+export declare function setDraftDirty(dirty: boolean): void;
+/**
+ * Emits global CustomEvent to notify all components of draft sandbox mutations.
+ */
+export declare function dispatchDraftChange(): void;
+/**
+ * Subscribes to changes in draft mode status and dirty flag.
+ */
+export declare function subscribeToDraftStatus(callback: (status: {
+    isActive: boolean;
+    isDirty: boolean;
+}) => void): () => void;
+/**
+ * Returns current cloud draft sync status.
+ */
+export declare function getCloudDraftSyncStatus(): CloudDraftSyncStatus;
+/**
+ * Subscribes to cloud draft sync status events.
+ */
+export declare function subscribeToCloudDraftSync(callback: (detail: DraftSyncStatusEventDetail) => void): () => void;
+/**
+ * Clears all in-memory draft canvas documents, flags, and any lingering storage keys.
+ */
+export declare function clearDraftStorage(): void;
+/**
+ * Checks whether any draft data currently exists in memory or persistent storage.
+ */
+export declare function hasDraftKeys(): boolean;
+/**
+ * Queries active draft from Supabase engine_drafts table.
+ */
+export declare function fetchActiveCloudDraft(): Promise<CloudDraftData | null>;
+/**
+ * Syncs the current in-memory draft state to Supabase engine_drafts.
+ */
+export declare function syncDraftToCloud(): Promise<boolean>;
+/**
+ * Triggers debounced background auto-sync to Supabase engine_drafts.
+ */
+export declare function triggerDebouncedCloudDraftSync(): void;
+/**
+ * Initializes a Developer Mode draft editing sandbox.
+ * Populates in-memory draft state from Supabase engine_drafts or live published baseline.
+ * Zero writes of canvas documents to localStorage.
+ */
+export declare function initDraftSession(forceFresh?: boolean): Promise<void>;
+/**
+ * Discards all uncommitted draft changes and reverts the workspace to the active live published state.
+ */
+export declare function discardDraftSession(): Promise<void>;
+/**
+ * Synchronizes draft storage to mirror the newly published live baseline.
+ * Resets the draft dirty state to clean (hasUnpublishedChanges = false).
+ */
+export declare function syncDraftWithPublished(canvases: Record<string, NodeCanvasDocument>, _contentOverrides?: Record<string, string>, newBaseId?: string): void;

package/dist/services/drivePhotoSyncService.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Drive Photo Synchronization & Differential Reconciliation Service
+ * Folio Engine
+ *
+ * Implements Subtask 6.1:
+ * - O(1) Map-based Differential Reconciliation of Google Drive photos with source gallery records
+ * - Identity preservation and coordinator custom-title retention
+ * - Natural numeric filename sorting (01_, 02_, ... 10_)
+ * - Machine filename auto-cleaning into editorial titles
+ * - Fallback high-res and thumbnail URL constructor
+ * - Google Drive REST API v3 Image Fetcher
+ */
+import type { DrivePhotoFile, SyncedSourceItem, DriveReconciliationResult, SyncFolderPhotosResult } from '../types/source';
+/**
+ * Strips machine prefixes, extensions, and sequence numbers from raw filenames
+ * converting them into clean editorial titles.
+ */
+export declare function cleanDriveFileName(rawName: string): string;
+/**
+ * Performs natural numeric comparison on filenames to ensure sequential ordering
+ * (e.g. "01_Photo.jpg", "02_Photo.jpg", "10_Photo.jpg").
+ */
+export declare function compareNaturalFilenames(a: string, b: string): number;
+/**
+ * Transforms Google Drive thumbnail link into permanent high-resolution endpoint (=s1600 or sz=w1600).
+ * Bypasses ephemeral /drive-storage/ URLs by strictly generating permanent Google Drive endpoints.
+ * Supports edge media proxy generation (/api/media/drive/:fileId?w=1600) when preferEdgeProxy is true.
+ */
+export declare function formatHighResDriveUrl(thumbnailLink?: string, fileId?: string, preferEdgeProxy?: boolean): string;
+/**
+ * Returns permanent thumbnail URL, bypassing ephemeral /drive-storage/ session links.
+ * Supports edge media proxy generation (/api/media/drive/:fileId?w=320) when preferEdgeProxy is true.
+ */
+export declare function formatThumbnailDriveUrl(thumbnailLink?: string, fileId?: string, preferEdgeProxy?: boolean): string;
+/**
+ * Pure O(1) Map Differential Reconciliation Engine.
+ * Reconciles incoming Google Drive photo files against existing synced source records.
+ *
+ * Invariants:
+ * 1. Preserves existing item instances, IDs, and custom titles (isCustomTitle: true).
+ * 2. Appends new images with clean titles and natural orderIndex.
+ * 3. Prunes images deleted from Google Drive.
+ * 4. Yields accurate differential stats and hasChanged boolean.
+ */
+export declare function reconcileDrivePhotos(existingItems: SyncedSourceItem[], incomingFiles: DrivePhotoFile[], pointId: string): DriveReconciliationResult;
+/**
+ * Queries Google Drive REST API v3 to list image files within a public folder root.
+ * Supports public shared drives, resource keys, subfolder scanning, and Google Workspace links.
+ */
+export declare function fetchDriveFolderImages(folderUrlOrId: string): Promise<DrivePhotoFile[]>;
+/**
+ * High-level orchestration function for syncing a node's Google Drive folder.
+ * Subtask 6.2: Service Orchestration Function.
+ *
+ * 1. Fetches image files from Google Drive REST API v3
+ * 2. Reconciles incoming files with existing synced items (O(1) Map diff)
+ * 3. Persists the reconciled photo manifest into BaaS / LocalStorage cache via upsertLiveSourceSource
+ * 4. Dispatches reactive update events and returns the reconciled items, diff stats, and updated source
+ */
+export declare function syncFolderPhotos(pointId: string, folderUrl: string, existingPhotos?: SyncedSourceItem[], authToken?: string): Promise<SyncFolderPhotosResult>;

package/dist/services/driveVerificationService.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Drive Verification Service
+ * Folio Engine
+ * Automated Google Drive MOV Repository & Folder Verification
+ *
+ * Implements a hybrid verification engine:
+ * 1. Google Drive REST API v3: Directly verifies folder existence, public accessibility,
+ *    and extracts official folder titles.
+ * 2. Graceful Fallback: Handles offline, quota, or network restrictions without blocking coordinators.
+ */
+export interface DriveVerificationResult {
+    status: 'valid' | 'restricted' | 'not_a_folder' | 'unverified' | 'invalid_format';
+    folderId?: string;
+    folderTitle?: string;
+    mimeType?: string;
+    message?: string;
+    apiError?: {
+        statusCode?: number;
+        reason?: string;
+        rawMessage?: string;
+    };
+}
+/**
+ * Extracts canonical Google Drive folder ID from a URL.
+ */
+export declare function extractDriveFolderId(url: string): string | null;
+/**
+ * Extracts optional Google Drive resource key from URL query parameters.
+ */
+export declare function extractResourceKey(url: string): string | null;
+/**
+ * Automatically verifies a Google Drive folder URL:
+ * - Checks if the folder exists
+ * - Verifies that it is publicly accessible ("Anyone with the link can view")
+ * - Supports Google Workspace Shared Drives (supportsAllDrives=true)
+ * - Detects API Key / deployment referrer restrictions and falls back gracefully
+ * - Formats explicit diagnostic edge error details (HTTP codes, API messages, network issues)
+ * - Discovers the folder's official title
+ * - Verifies that it is actually a folder (not a lone file)
+ */
+export declare function verifyDriveFolderUrl(url: string): Promise<DriveVerificationResult>;

package/dist/services/edgePreBakeService.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Folio Engine — Edge KV Pre-Baking Pipeline Service
+ * Location: src/services/edgePreBakeService.ts
+ * Specification: docs/tasks/task15_3_edge_kv_pre_baking_pipeline.md
+ *
+ * Implements:
+ * 1. Publish-time AST compiler for all 5 nodes.
+ * 2. Deterministic Google Drive URL rewriting to edge proxy endpoints (/api/media/drive/:fileId?w=800).
+ * 3. Pre-calculated multi-density responsive srcSet (400w, 800w, 1600w).
+ * 4. Bundles indicator chart datasets & source metadata directly into public payloads.
+ * 5. Atomic bulk deployment to Cloudflare KV REST API with resilient offline fallback.
+ */
+import type { PublicNodePayload, PublicPortalManifestPayload, CachedIndicatorDataset, SyncedSourceMetadata } from '../types/edge';
+import type { NodeCanvasDocument } from '../types/canvas';
+import type { PublishedSnapshot } from '../types/history';
+export declare const TRANSFORM_BREAKPOINTS: readonly [400, 800, 1600];
+export declare const DEFAULT_SIZES_ATTRIBUTE = "(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 800px";
+export declare const DEFAULT_PHOTO_ASPECT_RATIO = "16/9";
+export interface CloudflareKVCredentials {
+    accountId?: string;
+    namespaceId?: string;
+    apiToken?: string;
+}
+export interface KVPairPayload {
+    key: string;
+    value: string;
+    expiration?: number;
+    expiration_ttl?: number;
+    metadata?: unknown;
+}
+export interface KVDeployResult {
+    success: boolean;
+    deployedCount: number;
+    warning?: string;
+    error?: string;
+}
+export interface PreBakeResult {
+    success: boolean;
+    snapshotId: string;
+    transformedNodes: string[];
+    totalKvKeys: number;
+    deployResult: KVDeployResult;
+}
+export interface PreBakeCompileOptions {
+    nodeIds?: string[];
+    chartDatasets?: Record<string, CachedIndicatorDataset>;
+    sourceMetadata?: Record<string, SyncedSourceMetadata>;
+    credentials?: CloudflareKVCredentials;
+}
+/**
+ * Recursively walks the Canvas AST and pre-bakes responsive edge proxy URLs for all photo elements.
+ * Preserves local assets, data URLs, and custom aspect ratios untouched.
+ */
+export declare function transformCanvasAst(canvasDoc: NodeCanvasDocument): NodeCanvasDocument;
+/**
+ * Gathers cached indicator datasets for a node document.
+ */
+export declare function gatherIndicatorDatasets(nodeId: string, provided?: Record<string, CachedIndicatorDataset>): Record<string, CachedIndicatorDataset>;
+/**
+ * Gathers synced source metadata for a node document.
+ */
+export declare function gatherSourceMetadata(nodeId: string, provided?: Record<string, SyncedSourceMetadata>): Record<string, SyncedSourceMetadata>;
+/**
+ * Compiles a single node's pre-baked PublicNodePayload ready for KV deployment.
+ */
+export declare function compilePublicNodePayload(nodeId: string, snapshot: PublishedSnapshot, options?: PreBakeCompileOptions): PublicNodePayload;
+/**
+ * Compiles the PublicPortalManifestPayload pointing to the active published snapshot.
+ */
+export declare function compilePortalManifest(snapshot: PublishedSnapshot, nodeIds?: string[]): PublicPortalManifestPayload;
+/**
+ * Dispatches bulk key-value pairs to Cloudflare KV REST API.
+ * In offline dev environments or when credentials are not configured,
+ * logs a friendly warning and returns cleanly without throwing.
+ */
+export declare function deployPayloadsToCloudflareKV(payloads: KVPairPayload[], credentials?: CloudflareKVCredentials): Promise<KVDeployResult>;
+/**
+ * Top-level Orchestrator: Pre-bakes all 5 nodes and manifest,
+ * deploying atomically to Cloudflare KV.
+ */
+export declare function compileAndDeployToEdgeKV(snapshot: PublishedSnapshot, options?: PreBakeCompileOptions): Promise<PreBakeResult>;