@devcabs/folio-engine 0.0.0-stage → 0.1.0

package/dist/utils/contentDb.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Content Database & Dynamic Text Registry Engine
+ * Folio Engine
+ *
+ * Implements a reactive, client-side dual-channel content repository.
+ * Strictly separates uncommitted drafts (isDevMode = true) from canonical live
+ * published text (isDevMode = false), preventing cross-talk and leaks to public visitors.
+ */
+export declare const getLiveContentStorageKey: (ns?: string) => string;
+export declare const STORAGE_KEY_LIVE_CONTENT: string;
+export declare const getDraftContentStorageKey: (ns?: string) => string;
+export declare const STORAGE_KEY_DRAFT_CONTENT: string;
+export declare const getLegacyContentStorageKey: (ns?: string) => string;
+export declare const STORAGE_KEY_LEGACY_CONTENT: string;
+export declare const STORAGE_KEY_CONTENT_OVERRIDES: string;
+export declare const EVENT_LIVE_CONTENT_CHANGE = "engine-live-content-change";
+export declare const EVENT_DRAFT_CONTENT_CHANGE = "engine-draft-content-change";
+/**
+ * Retrieves the current text for a given key with strict channel isolation.
+ * Public visitors (isDevMode = false) strictly read canonical live overrides;
+ * Coordinators (isDevMode = true) read draft overrides, falling back to live before hardcoded defaults.
+ */
+export declare function getContent(key: string, defaultValue: string, isDevMode?: boolean): string;
+/**
+ * Checks whether a specific content key currently has a custom override saved.
+ */
+export declare function hasContentOverride(key: string, isDevMode?: boolean): boolean;
+/**
+ * Persists an edited text override strictly isolated to the specified channel.
+ */
+export declare function setContent(key: string, value: string, isDevMode?: boolean): void;
+/**
+ * Retrieves structured content (link, image, file, or object) from the DB.
+ * Gracefully parses JSON if serialized, falling back to defaultValue.
+ */
+export declare function getContentObject<T>(key: string, defaultValue: T, isDevMode?: boolean): T;
+/**
+ * Persists a structured object into the DB by serializing it to JSON.
+ */
+export declare function setContentObject<T>(key: string, value: T, isDevMode?: boolean): void;
+/**
+ * Resets a content key back to its default value by removing the override.
+ */
+export declare function resetContent(key: string, isDevMode?: boolean): void;
+/**
+ * Returns a copy of all current content overrides for the targeted channel.
+ */
+export declare function getAllContentOverrides(isDevMode?: boolean): Record<string, string>;
+/**
+ * Resets all content overrides back to system defaults.
+ */
+export declare function resetAllContentOverrides(isDevMode?: boolean): void;
+/**
+ * Replaces all content overrides and notifies all reactive subscribers.
+ * Used during historical snapshot restoration.
+ */
+export declare function setAllContentOverrides(overrides: Record<string, string>, isDevMode?: boolean): void;
+/**
+ * Invalidates the in-memory cache and forces next read from storage.
+ */
+export declare function invalidateContentCache(): void;
+/**
+ * Reads content overrides strictly from the canonical live/published channel.
+ */
+export declare function getLiveContentOverrides(): Record<string, string>;
+/**
+ * Persists content overrides strictly to the canonical live/published channel.
+ */
+export declare function setLiveContentOverrides(overrides: Record<string, string>): void;
+/**
+ * Subscribes to content changes strictly scoped by channel.
+ */
+export declare function subscribeToContentChange(callback: (detail: {
+    key: string;
+    value: string | null;
+}) => void, isDevMode?: boolean): () => void;
+/**
+ * Subscribes a listener to updates for a specific content key.
+ * Used by useSyncExternalStore for granular, zero-overhead store subscriptions.
+ */
+export declare function subscribeContentKey(key: string, callback: () => void, isDevMode?: boolean): () => void;
+/**
+ * Snapshot getter for useSyncExternalStore.
+ * Guarantees stable raw string snapshots from in-memory cache.
+ */
+export declare function getContentSnapshot(key: string, defaultValue: string, isDevMode?: boolean): string;

package/dist/utils/devSecurity.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Security and Cryptographic Primitives for Developer Mode
+ * Task 4.5.0: docs/tasks/task4_5_0_developer_mode.md
+ *
+ * Implements salted SHA-256 hashing via native Web Crypto API.
+ * The raw 4-digit PIN is NEVER stored in cleartext.
+ */
+export declare const getDevSalt: (ns?: string) => any;
+export declare const DEV_SALT: any;
+export declare const EXPECTED_PIN_HASH = "73b1e1cccbe22119e026c333e9de035db2a553f8acecdb5406af95f59bf46178";
+export declare const SESSION_DURATION_MS: number;
+export declare const LOCKOUT_DURATION_MS: number;
+export declare const MAX_ATTEMPTS = 5;
+export declare const getDevUnlockedAtKey: (ns?: string) => string;
+export declare const STORAGE_KEY_UNLOCKED_AT: string;
+export declare const getDevLockoutUntilKey: (ns?: string) => string;
+export declare const STORAGE_KEY_LOCKOUT_UNTIL: string;
+export declare const getDevFailedAttemptsKey: (ns?: string) => string;
+export declare const STORAGE_KEY_FAILED_ATTEMPTS: string;
+/**
+ * Zero-dependency pure-TypeScript SHA-256 implementation.
+ * Used as a seamless fallback when window.crypto.subtle is unavailable
+ * (e.g. non-HTTPS environments, IP-based staging deploys, or restricted WebViews).
+ */
+export declare function sha256Fallback(ascii: string): string;
+/**
+ * Computes salted SHA-256 hex digest for a given input PIN string.
+ * Native Web Crypto API execution: SHA-256(`${salt}:${pin}`) with
+ * automatic graceful fallback to pure-TypeScript SHA-256.
+ */
+export declare function hashPin(pin: string, salt?: string): Promise<string>;
+/**
+ * Verifies a 4-digit numeric PIN against the salted SHA-256 hash digest.
+ */
+export declare function verifyPin(inputPin: string, salt?: string, expectedHash?: string): Promise<boolean>;
+/**
+ * Verifies whether the runtime environment is a PC / Desktop viewport.
+ * Developer Mode is strictly locked to viewports >= 1024px with fine pointer precision.
+ */
+export declare function isDesktopDevice(): boolean;
+/**
+ * Retrieves the stored session unlock timestamp from sessionStorage.
+ */
+export declare function getSessionUnlockTime(): number | null;
+/**
+ * Stores the session unlock timestamp in sessionStorage.
+ */
+export declare function setSessionUnlockTime(timestamp: number): void;
+/**
+ * Clears the session unlock timestamp from sessionStorage.
+ */
+export declare function clearSessionUnlockTime(): void;
+/**
+ * Evaluates whether a session timestamp is still active (< 30 minutes).
+ */
+export declare function isSessionValid(unlockedAt: number | null, now?: number): boolean;
+/**
+ * Calculates remaining session duration in minutes (rounded up).
+ */
+export declare function getRemainingSessionMinutes(unlockedAt: number | null, now?: number): number;
+/**
+ * Retrieves the lockout expiration timestamp if active.
+ */
+export declare function getLockoutUntil(): number | null;
+/**
+ * Stores the lockout expiration timestamp.
+ */
+export declare function setLockoutUntil(timestamp: number): void;
+/**
+ * Clears the lockout expiration timestamp.
+ */
+export declare function clearLockoutUntil(): void;
+/**
+ * Retrieves current failed attempts count.
+ */
+export declare function getFailedAttempts(): number;
+/**
+ * Updates failed attempts count.
+ */
+export declare function setFailedAttempts(count: number): void;
+/**
+ * Resets failed attempts count.
+ */
+export declare function resetFailedAttempts(): void;

package/dist/utils/mediaUrl.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Folio Engine — Client Media URL Utilities for Cloudflare Edge Proxy
+ * Location: src/utils/mediaUrl.ts
+ * Specification: docs/tasks/task15_2_edge_media_proxy_and_stream_transcoder.md
+ */
+export declare const ALLOWED_EDGE_WIDTHS: readonly [320, 400, 600, 800, 1200, 1600];
+export type EdgeWidth = (typeof ALLOWED_EDGE_WIDTHS)[number];
+/**
+ * Clamps or snaps an arbitrary image pixel width to the nearest allowed edge bucket.
+ */
+export declare function normalizeEdgeWidth(rawWidth: number): EdgeWidth;
+/**
+ * Extracts a Google Drive alphanumeric file ID from a raw ID or standard Drive URL formats:
+ * - Direct ID: 1ABCxyz0123456789_-
+ * - Thumbnail URL: https://drive.google.com/thumbnail?id=1ABC...&sz=w1600
+ * - File View URL: https://drive.google.com/file/d/1ABC.../view
+ * - Open URL: https://drive.google.com/open?id=1ABC...
+ */
+export declare function extractDriveFileId(input: string): string | null;
+export interface EdgeMediaUrlOptions {
+    width?: number;
+    format?: 'auto' | 'webp' | 'jpeg';
+}
+/**
+ * Generates an edge media proxy URL pointing to /api/media/drive/:fileId
+ */
+export declare function buildEdgeMediaUrl(fileIdOrUrl: string, options?: EdgeMediaUrlOptions): string;
+/**
+ * Generates a responsive HTML `srcset` attribute value mapping to edge media proxy buckets.
+ * Defaults to [400, 800, 1200, 1600] for optimal mobile and high-DPI rendering.
+ */
+export declare function buildEdgeSrcSet(fileIdOrUrl: string, widths?: readonly number[] | number[]): string;

package/dist/utils/modalActions.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Folio Engine — Canonical Modal & Dialog Positive Action Utilities
+ * Handles Ctrl+Enter / Cmd+Enter positive action discovery and triggering.
+ */
+export declare function registerActiveModal(el: HTMLElement | null): void;
+export declare function unregisterActiveModal(el: HTMLElement | null): void;
+export declare function isTopmostModal(el: HTMLElement | null): boolean;
+/**
+ * Checks if a keyboard event corresponds to the canonical positive submission shortcut:
+ * Ctrl+Enter (Windows/Linux) or Cmd+Enter (Mac).
+ */
+export declare function isPositiveShortcut(e: KeyboardEvent | React.KeyboardEvent): boolean;
+/**
+ * Verifies whether an element is an enabled, visible, clickable positive candidate.
+ */
+export declare function isClickablePositiveCandidate(el: HTMLElement | null): el is HTMLElement;
+/**
+ * Discovers the canonical positive action element (button or form) inside a modal container.
+ * Priority:
+ * 1. Explicit data attributes: [data-positive="true"], [data-action="confirm"|"save"|"submit"|"primary"]
+ * 2. Form submit button: button[type="submit"]:not([disabled])
+ * 3. Primary/Admin variant buttons: button[data-variant="primary"|"admin"], button[data-primary="true"]
+ * 4. Text-matched buttons (Save, Submit, Publish, Add, Confirm, Next, etc.)
+ * 5. Containing form (for form.requestSubmit())
+ */
+export declare function findPositiveActionElement(container: HTMLElement | null): HTMLElement | null;
+/**
+ * Triggers the positive action element cleanly:
+ * - If form: calls requestSubmit() or submits
+ * - If button: calls .click()
+ */
+export declare function triggerPositiveAction(element: HTMLElement | null): boolean;

package/dist/utils/node-sections.d.ts

@@ -0,0 +1,15 @@
+import type { NodeItem } from '../types/node';
+import type { NavItem } from '../types/navigation';
+export interface NodeSection extends NavItem {
+    id: string;
+    label: string;
+    number?: string;
+    href: string;
+}
+/**
+ * Generates the semantic sub-sections for a dedicated node page.
+ * Strictly binds to authentic stages, project indicators status, and source.
+ */
+export declare function getNodeSections(node: NodeItem): NavItem[];
+export type PageSection = NodeSection;
+export declare const getPageSections: typeof getNodeSections;

package/dist/utils/page-sections.d.ts

@@ -0,0 +1 @@
+export * from './node-sections';

package/dist/utils/runtime-env.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Runtime environment separation (Task 11.98).
+ * Pure functions: no globals read inside decision logic, so they are unit-testable.
+ */
+export declare const PROD_PROJECT_REF = "mjuwqlxdxhujqiqpkcaj";
+/** Hostnames allowed to WRITE to the production database. */
+export declare const PROD_WRITE_HOSTS: readonly string[];
+export type TargetVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+export declare function urlTargetsProdProject(url: string): boolean;
+export declare function isProductionBuild(): boolean;
+/** L2: does the configured DB match the build mode? */
+export declare function evaluateSupabaseTarget(url: string, prodBuild: boolean): TargetVerdict;
+/** L3: may a mutating request to this Supabase URL be sent from this page host? */
+export declare function isWriteAllowed(supabaseUrl: string, pageHostname: string, prodBuild: boolean): boolean;
+export declare function currentTargetLabel(supabaseUrl: string): 'PROD-DB' | 'DEV-DB';

package/dist/utils/scrollLock.d.ts

@@ -0,0 +1,10 @@
+/**
+ * scrollLock.ts
+ * Folio Engine
+ *
+ * Universal scroll lock coordinator with reference-counting.
+ * Safely coordinates scroll locking between stacked Modals, Drawers, and Lightboxes.
+ * Automatically computes desktop scrollbar compensation to eliminate layout jitter.
+ */
+export declare function acquireScrollLock(): void;
+export declare function releaseScrollLock(): void;

package/dist/utils/smooth-scroll.d.ts

@@ -0,0 +1,24 @@
+/**
+ * smooth-scroll.ts
+ * Precision cinematic smooth scrolling engine — Folio Engine
+ *
+ * Replaces the browser's jarring, high-velocity default smooth scroll (~300ms)
+ * with a stately, leisurely editorial motion curve (~1000ms - 1200ms) that allows
+ * visitors to comfortably appreciate the illuminated serpentine conduit path and
+ * milestone transitions.
+ */
+/**
+ * Aborts any ongoing cinematic smooth scroll immediately.
+ */
+export declare function cancelCinematicScroll(): void;
+export interface SmoothScrollOptions {
+    /** Target vertical scroll position in pixels */
+    top: number;
+    /** Duration in milliseconds. Defaults to dynamic calculation based on distance (~2300ms–2600ms per fold) */
+    duration?: number;
+    /** Callback fired when scroll completes */
+    onComplete?: () => void;
+    /** Whether user wheel/touch events can cancel this scroll. Defaults to true. */
+    interruptible?: boolean;
+}
+export declare function cinematicScrollTo({ top, duration, onComplete, interruptible }: SmoothScrollOptions): void;

package/dist/utils/source.d.ts

@@ -0,0 +1,25 @@
+import type { SourceSource } from '../types/source';
+/**
+ * Normalizes point and node identifiers to ensure consistent lookup.
+ * Handles both "node-access" and "access" seamlessly, trimming whitespace
+ * and lowering case. Defensively handles null/undefined or empty input.
+ */
+export declare function normalizePointId(pointId: string): string;
+/**
+ * Safely retrieves the official SourceSource for a given node or point ID.
+ * Incorporates dynamic client-side Content DB overrides if configured.
+ * Returns null if the source is not registered or invalid.
+ */
+export declare function getSourceSource(pointId: string): SourceSource | null;
+/**
+ * Matches canonical Google Drive folder URL patterns:
+ * - https://drive.google.com/drive/folders/{folderId}
+ * - https://drive.google.com/drive/u/{userIndex}/folders/{folderId}
+ * - https://drive.google.com/open?id={folderId}
+ */
+export declare const GOOGLE_DRIVE_FOLDER_REGEX: RegExp;
+/**
+ * Validates whether a given URL string is a valid Google Drive folder URL.
+ * Defensively handles null, undefined, non-string, or malformed inputs.
+ */
+export declare function isValidDriveFolderUrl(url: string): boolean;

package/dist/utils/storage.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Canonical browser storage accessor for Folio Engine.
+ * Safely accesses window.localStorage, falling back to window.sessionStorage.
+ */
+export declare function getStorage(): Storage | null;
+/**
+ * Task 11.2.G3: Zero-LocalStorage Document Policy Enforcement.
+ * Purges legacy draft and bloated document payloads from window.localStorage,
+ * preserving solely small scalar session tokens (folio_session_id, folio_dev_unlocked_at,
+ * folio_live_active_published_id, folio_draft_active, folio_draft_dirty).
+ * Enforces a strict < 5 KB total localStorage footprint.
+ */
+export declare function purgeLegacyDocumentStorage(): void;

package/dist/utils/supabase-config.d.ts

@@ -0,0 +1,29 @@
+export interface SupabaseConfig {
+    url: string;
+    anonKey: string;
+}
+/**
+ * Canonical Supabase endpoint configuration parser.
+ * Validates against placeholder defaults and trailing slashes.
+ */
+export declare function getSupabaseConfig(): SupabaseConfig | null;
+export declare const getMissingTablesStorageKey: (ns?: string) => string;
+export declare const STORAGE_KEY_MISSING_TABLES: string;
+/**
+ * Checks whether a Supabase table is known to be available.
+ * Returns false if the table previously returned 404 in this browser session.
+ * dev_mode_session is always queried to enforce institutional exclusivity.
+ */
+export declare function isTableAvailable(tableName: string): boolean;
+/**
+ * Marks a Supabase table as missing (404) for the remainder of this session.
+ */
+export declare function markTableMissing(tableName: string): void;
+/**
+ * Marks a Supabase table as available, removing any previously memoized 404 block.
+ */
+export declare function markTableAvailable(tableName: string): void;
+/**
+ * Resets memoized missing tables (used in automated tests and session resets).
+ */
+export declare function resetMissingTablesForTesting(): void;

package/dist/utils/supabase-write-guard.d.ts

@@ -0,0 +1,15 @@
+interface GuardTarget {
+    fetch: typeof fetch;
+    location?: {
+        hostname: string;
+    };
+}
+/**
+ * Wraps fetch. Any mutating request whose URL starts with the configured
+ * Supabase URL is rejected (HTTP 403 Response, never sent) unless isWriteAllowed().
+ * Idempotent. Call once, before any service module issues requests.
+ */
+export declare function installSupabaseWriteGuard(supabaseUrl?: string | undefined, target?: GuardTarget, prodBuild?: boolean): void;
+/** Test helper only. */
+export declare function resetWriteGuardForTesting(): void;
+export {};

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@devcabs/folio-engine",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/folio.umd.cjs",
+  "module": "./dist/folio.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/folio.js",
+      "require": "./dist/folio.umd.cjs"
+    },
+    "./style.css": "./dist/style.css"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "dependencies": {
+    "d3-array": "^3.2.4",
+    "d3-scale": "^4.0.2",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.21.0",
+    "@types/d3-array": "^3.2.2",
+    "@types/d3-scale": "^4.0.9",
+    "@types/node": "^22.13.9",
+    "@types/react": "^19.0.10",
+    "@types/react-dom": "^19.0.4",
+    "@typescript-eslint/eslint-plugin": "^8.26.0",
+    "@typescript-eslint/parser": "^8.26.0",
+    "@vitejs/plugin-react": "^4.3.4",
+    "eslint": "^9.21.0",
+    "tsx": "^4.19.3",
+    "typescript": "^5.7.3",
+    "vite": "^6.2.0",
+    "vitest": "^3.0.7"
+  },
+  "scripts": {
+    "dev": "vite --port 5174",
+    "start": "vite --port 5174",
+    "build": "npm run test:tokens && tsc --noEmit && vite build",
+    "build:lib": "npm run test:tokens && vite build -c vite.config.lib.ts && tsc -p tsconfig.lib.json",
+    "preview": "vite preview --port 5174",
+    "test:purity": "vitest run tests/purity",
+    "test:tokens": "tsx scripts/verify-token-aliases.ts",
+    "lint": "eslint .",
+    "prepack": "npm run build:lib"
+  },
+  "files": [
+    "dist"
+  ]
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.