@pyric/ui 0.1.0-alpha.11 → 0.1.0-alpha.13

package/src/storage/pendingPrefixes.ts

@@ -0,0 +1,125 @@
+/**
+ * Pending (not-yet-materialized) folder prefixes — pure reducer, no React.
+ *
+ * MECHANISM DECISION (create-folder). GCS has no real folders: a
+ * "folder" exists only as a shared prefix of object names. Two honest
+ * ways to let a user create one before it contains anything:
+ *
+ *  a) write a zero-byte `<path>/` placeholder object (the emulator-UI
+ *     convention — `useObjectUpload.createFolder` does this): the
+ *     folder survives reloads, but every created folder deposits a
+ *     phantom object in the sandbox store, and the Studio worker
+ *     `StorageApi` path has no channel for the trailing-slash ref;
+ *
+ *  b) hold the created prefix as CLIENT-SIDE PENDING STATE and let the
+ *     first upload into it materialize it for real. The store stays
+ *     byte-for-byte clean — nothing is written until a file is — at
+ *     the cost that a created-then-abandoned empty folder disappears
+ *     on reload.
+ *
+ * Studio's create-folder flow uses (b): the sandbox store is the
+ * user's actual data and must not accrue placeholder objects, and the
+ * disappearing-empty-folder tradeoff is acceptable BECAUSE the UI
+ * labels pending rows as session-only ("empty" badge + empty-state
+ * copy in `StoragePane`). (a) remains available to consumers who want
+ * persistent empty folders in sandbox-only setups.
+ *
+ * State is a sorted list of normalized bucket-rooted prefix paths (no
+ * trailing slashes). Creating `stuff/things/cool` expands the whole
+ * chain — `stuff`, `stuff/things`, `stuff/things/cool` — so every
+ * ancestor level shows the folder while browsing (VS Code-style nested
+ * create). A successful upload MATERIALIZES its destination folder:
+ * the chain up to that folder leaves pending state (the real listing
+ * now surfaces those prefixes); pending descendants of other branches
+ * stay.
+ */
+
+import { normalizeStoragePath } from './hooks/usePathState.js';
+
+/** Sorted, deduped, normalized pending prefix paths. */
+export type PendingPrefixState = readonly string[];
+
+export type PendingPrefixAction =
+  /** Create a folder at `path` (absolute, bucket-rooted; nested paths
+   *  allowed) — adds the full ancestor chain. */
+  | { type: 'create'; path: string }
+  /** An object now exists directly under `path`: drop `path` and its
+   *  ancestors from pending (they are real prefixes now). */
+  | { type: 'materialize'; path: string }
+  /** Remove a session-only folder and every pending descendant beneath it. */
+  | { type: 'discard'; path: string }
+  | { type: 'clear' };
+
+/** `'a/b/c'` → `['a', 'a/b', 'a/b/c']`; `''` → `[]`. */
+export function expandPathChain(path: string): string[] {
+  const normalized = normalizeStoragePath(path);
+  if (normalized === '') return [];
+  const segments = normalized.split('/');
+  return segments.map((_, i) => segments.slice(0, i + 1).join('/'));
+}
+
+export const initialPendingPrefixes: PendingPrefixState = [];
+
+export function pendingPrefixReducer(
+  state: PendingPrefixState,
+  action: PendingPrefixAction,
+): PendingPrefixState {
+  switch (action.type) {
+    case 'create': {
+      const chain = expandPathChain(action.path).filter((p) => !state.includes(p));
+      if (chain.length === 0) return state;
+      return [...state, ...chain].sort();
+    }
+    case 'materialize': {
+      const real = new Set(expandPathChain(action.path));
+      if (real.size === 0) return state;
+      const next = state.filter((p) => !real.has(p));
+      return next.length === state.length ? state : next;
+    }
+    case 'discard': {
+      const path = normalizeStoragePath(action.path);
+      if (path === '') return state;
+      const next = state.filter((entry) => entry !== path && !entry.startsWith(`${path}/`));
+      return next.length === state.length ? state : next;
+    }
+    case 'clear':
+      return state.length === 0 ? state : initialPendingPrefixes;
+  }
+}
+
+/** Direct-child folder NAMES pending under `parentPath` (`''` = root),
+ *  sorted. The chain expansion guarantees every level is present, so a
+ *  simple parent match is exact. */
+export function pendingChildFolders(
+  state: PendingPrefixState,
+  parentPath: string,
+): string[] {
+  const parent = normalizeStoragePath(parentPath);
+  const prefix = parent === '' ? '' : `${parent}/`;
+  return state
+    .filter((p) => p.startsWith(prefix) && p !== parent && !p.slice(prefix.length).includes('/'))
+    .map((p) => p.slice(prefix.length));
+}
+
+/** Whether `path` itself is a pending (session-only) folder. */
+export function isPendingPrefix(state: PendingPrefixState, path: string): boolean {
+  return state.includes(normalizeStoragePath(path));
+}
+
+/**
+ * Validate a create-folder input (relative to the current folder;
+ * nested `a/b/c` allowed — VS Code semantics). Returns an error
+ * message or `null` when valid. Normalization tolerates stray/repeat
+ * slashes; `.`/`..` segments are rejected (GCS object names have no
+ * dot-segment semantics — accepting them would create unreachable
+ * names).
+ */
+export function folderInputError(input: string): string | null {
+  const normalized = normalizeStoragePath(input);
+  if (normalized === '') return 'Enter a folder name.';
+  const segments = normalized.split('/');
+  if (segments.some((s) => s === '.' || s === '..')) {
+    return 'Folder names may not be "." or "..".';
+  }
+  return null;
+}

package/src/storage/previews.tsx

@@ -0,0 +1,120 @@
+import { useEffect, useState, type ReactNode } from 'react';
+import type { FullMetadata } from 'pyric/storage';
+
+/** What a preview's `render` receives. `blob`/`blobUrl` are only
+ *  populated for previews that declared `needsBlob`. */
+export interface StoragePreviewContext {
+  metadata: FullMetadata;
+  blob: Blob | undefined;
+  blobUrl: string | undefined;
+}
+
+/**
+ * One entry in the content-type preview registry — the storage
+ * counterpart of the Firestore field-editor registry, keyed by a
+ * `match` predicate instead of a type name because content types are
+ * open-ended. First match wins; consumer previews run BEFORE the
+ * built-ins, so overriding `image/*` is just shipping your own
+ * matcher.
+ */
+export interface StoragePreview {
+  /** Diagnostic id — also stamped on the preview container as
+   *  `data-pyric-preview="<id>"`. */
+  id: string;
+  match: (metadata: FullMetadata) => boolean;
+  /** Ask the inspector to `loadBlob()` before rendering. Default
+   *  `false` (metadata-only previews render immediately). */
+  needsBlob?: boolean;
+  /**
+   * Skip the preview (and the blob download) for objects larger than
+   * this — the inspector renders its `data-pyric-preview-too-large`
+   * fallback instead. `undefined` = no cap.
+   */
+  maxBytes?: number;
+  render: (ctx: StoragePreviewContext) => ReactNode;
+}
+
+/** 256KB — the section 3 default cap for the text-family preview. */
+export const TEXT_PREVIEW_MAX_BYTES = 256 * 1024;
+
+function contentTypeOf(metadata: FullMetadata): string {
+  // `text/plain;charset=utf-8` → `text/plain`.
+  return (metadata.contentType ?? '').split(';')[0].trim().toLowerCase();
+}
+
+/** `image/*` → blob-URL `<img>`. */
+export const imagePreview: StoragePreview = {
+  id: 'image',
+  match: (md) => contentTypeOf(md).startsWith('image/'),
+  needsBlob: true,
+  render: ({ metadata, blobUrl }) =>
+    blobUrl ? (
+      <img data-pyric-preview-image src={blobUrl} alt={metadata.name} />
+    ) : null,
+};
+
+function TextPreviewBody({ blob, isJson }: { blob: Blob; isJson: boolean }) {
+  const [text, setText] = useState<string | undefined>(undefined);
+  useEffect(() => {
+    let cancelled = false;
+    blob.text().then((raw) => {
+      if (cancelled) return;
+      if (isJson) {
+        try {
+          setText(JSON.stringify(JSON.parse(raw), null, 2));
+          return;
+        } catch {
+          // Unparseable JSON falls through to the raw text.
+        }
+      }
+      setText(raw);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [blob, isJson]);
+  if (text === undefined) return null;
+  return <pre data-pyric-preview-text>{text}</pre>;
+}
+
+/** `text/*` + `application/json` → text panel, 256KB cap (bigger
+ *  objects fall through to the too-large fallback). JSON is
+ *  pretty-printed when parseable. */
+export const textPreview: StoragePreview = {
+  id: 'text',
+  match: (md) => {
+    const ct = contentTypeOf(md);
+    return ct.startsWith('text/') || ct === 'application/json';
+  },
+  needsBlob: true,
+  maxBytes: TEXT_PREVIEW_MAX_BYTES,
+  render: ({ metadata, blob }) =>
+    blob ? (
+      <TextPreviewBody
+        blob={blob}
+        isJson={contentTypeOf(metadata) === 'application/json'}
+      />
+    ) : null,
+};
+
+/** The section 3 defaults: image, text/json; everything else is
+ *  metadata-only (the inspector's `data-pyric-preview-none` state). */
+export const defaultStoragePreviews: ReadonlyArray<StoragePreview> = [
+  imagePreview,
+  textPreview,
+];
+
+/**
+ * Pick the preview for `metadata`: consumer previews first (override
+ * channel), then the built-ins, first `match` wins. `undefined`
+ * means metadata-only.
+ */
+export function selectStoragePreview(
+  metadata: FullMetadata,
+  consumerPreviews: ReadonlyArray<StoragePreview> | undefined,
+): StoragePreview | undefined {
+  for (const preview of [...(consumerPreviews ?? []), ...defaultStoragePreviews]) {
+    if (preview.match(metadata)) return preview;
+  }
+  return undefined;
+}

package/src/storage/storageApi.ts

@@ -0,0 +1,54 @@
+import { createContext, createElement, useContext, type ReactNode } from 'react';
+import { ref, listAll, getMetadata, getBlob, uploadBytes, deleteObject } from 'pyric/storage';
+
+/**
+ * The modular Storage fns the browse/inspect hooks call, as an INJECTABLE
+ * bundle (same pattern as `@pyric/ui`'s FirestoreApi / AuthApi).
+ *
+ * Default = in-process `pyric/storage`, so existing consumers are unchanged.
+ * Pyric Studio served mode injects the SharedWorker client bundle so the Storage
+ * surface browses the live worker object store. These ops are already async, so
+ * no sync/async wrinkle (unlike auth `listUsers`); the worker handles/refs are
+ * runtime-compatible at the surface the hooks use (`.fullPath` / `.name`).
+ *
+ * `uploadBytes` rides the same seam so `useObjectUpload` follows the injected
+ * backend: in-process writes are uncapped; the worker client's `uploadBytes`
+ * (base64 `storage.putBytes` over the MessagePort) enforces an 8 MiB payload
+ * cap on both ends — an over-cap upload fails that file's task with the typed
+ * `storage/...` too-large error and the rest of the batch proceeds.
+ *
+ * NOTE the rules gate (`useStorageRulesGate`) is NOT here: it reads in-process
+ * rules internals and no-ops on a handle without them (worker handles), which is
+ * the correct degrade (the worker enforces read rules on `listAll` server-side).
+ */
+export type StorageApi = Pick<
+  typeof import('pyric/storage'),
+  'ref' | 'listAll' | 'getMetadata' | 'getBlob' | 'uploadBytes' | 'deleteObject'
+>;
+
+const inProcessStorageApi: StorageApi = {
+  ref,
+  listAll,
+  getMetadata,
+  getBlob,
+  uploadBytes,
+  deleteObject,
+};
+
+const StorageApiContext = createContext<StorageApi>(inProcessStorageApi);
+
+/** Read the active Storage API bundle (defaults to in-process `pyric/storage`). */
+export function useStorageApi(): StorageApi {
+  return useContext(StorageApiContext);
+}
+
+/** Provide a Storage API bundle to the subtree (Studio's worker client). */
+export function StorageApiProvider({
+  value,
+  children,
+}: {
+  value: StorageApi;
+  children: ReactNode;
+}) {
+  return createElement(StorageApiContext.Provider, { value }, children);
+}

package/src/traffic/components/RuleHeatmap.tsx

@@ -0,0 +1,97 @@
+import type { ReactNode } from 'react';
+import type { RuleHeatmapEntry } from '../hooks/useRuleHeatmap.js';
+
+export interface RuleHeatmapProps {
+  /** Per-rule rollup from `useRuleHeatmap`. */
+  entries: RuleHeatmapEntry[];
+  /** Marks one rule row as the active selection. */
+  selectedRuleIndex?: number;
+  /**
+   * Fired when a rule row is clicked — wire this to the log filter
+   * for the cross-view "click a rule, see its traffic" interaction.
+   */
+  onSelectRule?: (ruleIndex: number) => void;
+  emptyState?: ReactNode;
+  className?: string;
+}
+
+/** Buckets the deny ratio into discrete heat levels for CSS. */
+function heatBucket(denyRatio: number): 'none' | 'low' | 'medium' | 'high' {
+  if (denyRatio === 0) return 'none';
+  if (denyRatio <= 0.33) return 'low';
+  if (denyRatio <= 0.66) return 'medium';
+  return 'high';
+}
+
+/**
+ * Headless rule heatmap — one row per rule, busiest first. Each row
+ * exposes two styling channels:
+ *
+ * - `data-pyric-rule-heat` — a discrete bucket (`none`/`low`/
+ *   `medium`/`high`) by deny ratio, for threshold-based coloring.
+ * - `--pyric-deny-ratio` — the raw 0–1 ratio as a CSS custom
+ *   property, for a proportional bar / gradient.
+ *
+ * Counts render as separate elements (`data-pyric-rule-total`,
+ * `-allows`, `-denies`) so the consumer can show numbers, bars, or
+ * both.
+ *
+ * Styling hooks: `[data-pyric-ui="rule-heatmap"]`,
+ * `[data-pyric-rule-row]` (with `data-pyric-rule-index`,
+ * `data-pyric-rule-heat`, `data-pyric-selected`).
+ */
+export function RuleHeatmap({
+  entries,
+  selectedRuleIndex,
+  onSelectRule,
+  emptyState,
+  className,
+}: RuleHeatmapProps) {
+  if (entries.length === 0) {
+    return (
+      <div
+        className={className}
+        data-pyric-ui="rule-heatmap"
+        data-pyric-empty=""
+      >
+        {emptyState}
+      </div>
+    );
+  }
+
+  return (
+    <div className={className} data-pyric-ui="rule-heatmap">
+      <ul data-pyric-rule-heatmap-items="">
+        {entries.map((entry) => {
+          const selected = entry.ruleIndex === selectedRuleIndex;
+          return (
+            <li key={entry.ruleIndex} data-pyric-rule-entry="">
+              <button
+                type="button"
+                onClick={() => onSelectRule?.(entry.ruleIndex)}
+                data-pyric-rule-row=""
+                data-pyric-rule-index={entry.ruleIndex}
+                data-pyric-rule-heat={heatBucket(entry.denyRatio)}
+                data-pyric-selected={selected ? '' : undefined}
+                style={
+                  {
+                    '--pyric-deny-ratio': entry.denyRatio,
+                  } as React.CSSProperties
+                }
+              >
+                <span data-pyric-rule-label="">#{entry.ruleIndex}</span>
+                <span data-pyric-rule-operations="">
+                  {entry.operations.join(', ')}
+                </span>
+                <span data-pyric-rule-total="">{entry.total}</span>
+                <span data-pyric-rule-allows="">{entry.allows}</span>
+                <span data-pyric-rule-denies="">{entry.denies}</span>
+                <span data-pyric-rule-bar="" aria-hidden="true" />
+              </button>
+            </li>
+          );
+        })}
+      </ul>
+    </div>
+  );
+}

package/src/traffic/components/TrafficDetail.tsx

@@ -0,0 +1,160 @@
+import type { ReactNode } from 'react';
+import { Badge } from '../../primitives/Badge.js';
+import { JsonView } from '../../primitives/JsonView.js';
+import type { TrafficEvent } from '../types.js';
+import { defaultFormatTime, reasonVerdict } from './format.js';
+
+export interface TrafficDetailProps {
+  event: TrafficEvent;
+  /** Fired by the back affordance. When absent, no back button. */
+  onBack?: () => void;
+  /**
+   * Render-prop slot below the header — the playground drops its
+   * denial overlay (classification + LLM analysis) here. The library
+   * doesn't own that analysis.
+   */
+  renderClassification?: (event: TrafficEvent) => ReactNode;
+  /** Override the timestamp rendering. Default is `HH:MM:SS`. */
+  formatTime?: (at: number) => string;
+  className?: string;
+}
+
+function Section({
+  label,
+  children,
+}: {
+  label: string;
+  children: ReactNode;
+}) {
+  return (
+    <section data-pyric-traffic-section="" data-pyric-section-label={label}>
+      <h3 data-pyric-section-heading="">{label}</h3>
+      {children}
+    </section>
+  );
+}
+
+/**
+ * Headless drill-in panel for a single traffic event. Renders the
+ * header (result + origin + timestamp + method/path + matched rule),
+ * a consumer classification slot, then JSON sections for auth,
+ * request payload, and resource before/after via `<JsonView>`, plus
+ * the reasons list, `triggeredBy`, and `groupId`.
+ *
+ * `evalMs` appears here as a minor header field only — it is not a
+ * log column (local simulator; latency is de-featured per
+ * the design rationale).
+ *
+ * Styling hooks: `[data-pyric-ui="traffic-detail"]`,
+ * `[data-pyric-traffic-section]` (with `data-pyric-section-label`),
+ * `[data-pyric-traffic-reason]` (with `data-pyric-reason-verdict`).
+ */
+export function TrafficDetail({
+  event,
+  onBack,
+  renderClassification,
+  formatTime = defaultFormatTime,
+  className,
+}: TrafficDetailProps) {
+  const requestData = event.request?.resourceData ?? event.request?.data;
+  const durationMs = event.evalMs ?? event.durationMs ?? 0;
+
+  return (
+    <div className={className} data-pyric-ui="traffic-detail">
+      <header data-pyric-traffic-detail-header="">
+        {onBack ? (
+          <button
+            type="button"
+            onClick={onBack}
+            data-pyric-traffic-back=""
+            aria-label="Back to traffic log"
+          >
+            Back
+          </button>
+        ) : null}
+        <div data-pyric-traffic-detail-meta="">
+          <Badge kind={event.result}>{event.result}</Badge>
+          <span data-pyric-traffic-origin="">{event.origin}</span>
+          {event.service ? <span data-pyric-traffic-service="">{event.service}</span> : null}
+          <span data-pyric-traffic-time="">{formatTime(event.at)}</span>
+          <span data-pyric-traffic-eval-ms="">{durationMs.toFixed(1)}ms</span>
+        </div>
+        <p data-pyric-traffic-detail-title="">
+          <span data-pyric-traffic-method="">{event.method}</span>
+          <span data-pyric-traffic-path="">{event.path}</span>
+        </p>
+        {event.matchedRule ? (
+          <p data-pyric-traffic-matched-rule="">
+            matched rule #{event.matchedRule.ruleIndex} ·{' '}
+            {event.matchedRule.operations.join(', ')}
+          </p>
+        ) : null}
+      </header>
+
+      {renderClassification ? renderClassification(event) : null}
+
+      <Section label="AUTH">
+        <JsonView value={event.auth} />
+      </Section>
+
+      {requestData !== undefined ? (
+        <Section label="REQUEST · resource.data">
+          <JsonView value={requestData} />
+        </Section>
+      ) : null}
+
+      {event.resourceBefore !== undefined ? (
+        <Section label="RESOURCE BEFORE">
+          <JsonView
+            value={
+              event.resourceBefore.exists ? event.resourceBefore.data : null
+            }
+          />
+        </Section>
+      ) : null}
+
+      {event.resourceAfter !== undefined ? (
+        <Section label="RESOURCE AFTER">
+          <JsonView
+            value={
+              event.resourceAfter.exists ? event.resourceAfter.data : null
+            }
+          />
+        </Section>
+      ) : null}
+
+      {event.reasons.length > 0 ? (
+        <Section label="REASONS">
+          <ul data-pyric-traffic-reasons="">
+            {event.reasons.map((reason, i) => (
+              <li
+                key={i}
+                data-pyric-traffic-reason=""
+                data-pyric-reason-verdict={reasonVerdict(reason)}
+              >
+                {reason}
+              </li>
+            ))}
+          </ul>
+        </Section>
+      ) : null}
+
+      {event.triggeredBy ? (
+        <Section label="TRIGGERED BY">
+          <p data-pyric-traffic-triggered-by="">
+            <span data-pyric-traffic-method="">
+              {event.triggeredBy.method}
+            </span>
+            <span data-pyric-traffic-path="">{event.triggeredBy.path}</span>
+          </p>
+        </Section>
+      ) : null}
+
+      {event.groupId ? (
+        <Section label="GROUP">
+          <p data-pyric-traffic-group="">{event.groupId}</p>
+        </Section>
+      ) : null}
+    </div>
+  );
+}

package/src/traffic/components/TrafficGroupRow.tsx

@@ -0,0 +1,91 @@
+import { useState, type ReactNode } from 'react';
+import type { TrafficEvent } from '../types.js';
+import type { TrafficGroup } from '../hooks/useTrafficGroups.js';
+import { TrafficRow } from './TrafficRow.js';
+import type { TrafficGroupKind } from '../hooks/useTrafficGroups.js';
+
+/** Header text per group kind — the raw kind slug stays on the
+ *  `data-pyric-group-kind` attributes for styling/tests. */
+const GROUP_KIND_LABELS: Record<TrafficGroupKind, string> = {
+  batch: 'batch write',
+  transaction: 'transaction',
+  'listener-run': 'listener re-evals',
+};
+
+export interface TrafficGroupRowProps {
+  group: TrafficGroup;
+  /** Whether the group starts expanded. Default false — grouping
+   *  exists to collapse volume, so collapsed is the useful default. */
+  defaultExpanded?: boolean;
+  onSelect?: (event: TrafficEvent) => void;
+  selectedId?: string;
+  /** Passed through to each member `<TrafficRow>`. */
+  renderClassification?: (event: TrafficEvent) => ReactNode;
+  /** Passed through to each member `<TrafficRow>`. */
+  formatTime?: (at: number) => string;
+  className?: string;
+}
+
+/**
+ * A collapsible group row — one header summarizing a batch,
+ * transaction, or listener-run, expanding to the member rows. The
+ * header carries `data-pyric-group-kind` and a `data-pyric-group-*`
+ * count/deny rollup; expansion state is `data-pyric-expanded`.
+ *
+ * Styling hooks: `[data-pyric-traffic-group]`,
+ * `[data-pyric-traffic-group-header]` (with `data-pyric-group-kind`),
+ * `[data-pyric-traffic-group-members]`.
+ */
+export function TrafficGroupRow({
+  group,
+  defaultExpanded = false,
+  onSelect,
+  selectedId,
+  renderClassification,
+  formatTime,
+  className,
+}: TrafficGroupRowProps) {
+  const [expanded, setExpanded] = useState(defaultExpanded);
+
+  return (
+    <div
+      className={className}
+      data-pyric-traffic-group=""
+      data-pyric-group-kind={group.kind}
+      data-pyric-expanded={expanded ? '' : undefined}
+    >
+      <button
+        type="button"
+        onClick={() => setExpanded((e) => !e)}
+        data-pyric-traffic-group-header=""
+        data-pyric-group-kind={group.kind}
+        aria-expanded={expanded}
+      >
+        <span data-pyric-group-kind-label="">{GROUP_KIND_LABELS[group.kind]}</span>
+        <span data-pyric-group-count="">×{group.count}</span>
+        {group.denies > 0 ? (
+          <span data-pyric-group-denies="">{group.denies} denied</span>
+        ) : null}
+      </button>
+      {expanded ? (
+        <ul data-pyric-traffic-group-members="">
+          {group.events.map((event) => (
+            <li
+              key={event.id}
+              data-pyric-traffic-entry=""
+              data-pyric-traffic-id={event.id}
+            >
+              <TrafficRow
+                event={event}
+                selected={event.id === selectedId}
+                onSelect={onSelect}
+                renderClassification={renderClassification}
+                formatTime={formatTime}
+              />
+            </li>
+          ))}
+        </ul>
+      ) : null}
+    </div>
+  );
+}