rahman-resources 1.12.0 → 1.13.0

package/lib/contract-types.ts

@@ -91,31 +91,20 @@ export interface SliceContractProvides {
 }
 
 // ---------------------------------------------------------------------------
-// `bidir` block — Wave N+3 (Bidirectional Sync Detection Layer)
+// Generalisation gate
 // ---------------------------------------------------------------------------
+// (Formerly nested inside the Wave N+3 `bidir` block. BSDL was removed in
+// Sesi 2; the sync policy died with it, but the generalisation contract is
+// still consumed by scripts/validation/check-forbidden-terms.mjs — so it
+// lives on as a top-level field.)
 
 /**
- * How the kitab treats sync between this slice and consumer copies.
+ * Portability level of the slice source.
  *
- * - `auto-pr`: when `rr scan-consumers` sees an `up-needed` verdict on a
- *   consumer's `.kitab.json`, the operator workflow auto-opens a PR against
- *   the kitab. Reserved for slices with strict generalisation gates.
- * - `notify`: surface in the scan report; no auto-action.
- * - `manual`: default — operator picks up via `/rr-prep` + `/rr-send`.
- * - `frozen`: kitab refuses both UP and DOWN sync. Lock for retired slices.
- */
-export type SliceSyncPolicy = "auto-pr" | "notify" | "manual" | "frozen";
-
-/**
- * Generalisation level a consumer-side `.kitab.json` MUST claim before
- * `rr-send` accepts the push back into the kitab.
- *
- * - `portable`: no consumer-specific business terms baked in. UP-sync allowed.
- * - `needs-adapter`: requires a thin adapter wired by the consumer; UP-sync
- *   blocked until blockers are addressed (or the contract drops the slice
- *   to `consumer-locked`).
+ * - `portable`: no consumer-specific business terms baked in.
+ * - `needs-adapter`: requires a thin adapter wired by the consumer.
  * - `consumer-locked`: contains business-specific logic that cannot be
- *   generalised. Only DOWN-sync allowed.
+ *   generalised.
  */
 export type GeneralizationLevel =
   | "portable"
@@ -123,14 +112,15 @@ export type GeneralizationLevel =
   | "consumer-locked";
 
 /**
- * Generalisation contract — what the audit-bp `forbiddenTerms` rule scans
- * for, and which props the consumer MUST inject.
+ * Generalisation contract — what the forbidden-terms audit scans for, and
+ * which props the consumer MUST inject.
  */
 export interface SliceGeneralization {
   level: GeneralizationLevel;
   /**
    * Identifiers / business terms that MUST NOT appear in the slice source
-   * tree. Audit-bp scans .ts/.tsx files. Empty when the slice is generic.
+   * tree. check-forbidden-terms.mjs scans .ts/.tsx files. Empty when the
+   * slice is generic.
    */
   forbiddenTerms?: string[];
   /**
@@ -140,16 +130,6 @@ export interface SliceGeneralization {
   requiredProps?: string[];
 }
 
-/**
- * Bidirectional sync block. Optional, additive — slices without it default to
- * `{ syncPolicy: "manual", generalization: { level: "portable" } }` for
- * legacy compatibility with Wave N+1 contracts.
- */
-export interface SliceBidirContract {
-  syncPolicy: SliceSyncPolicy;
-  generalization: SliceGeneralization;
-}
-
 // ---------------------------------------------------------------------------
 // Top-level contract
 // ---------------------------------------------------------------------------
@@ -179,6 +159,6 @@ export interface SliceContract {
   conflicts?: string[];
   /** Map of previous-version → migration script id. */
   migrationFrom?: Record<string, string>;
-  /** Wave N+3 — bidirectional sync policy + generalisation gate. */
-  bidir?: SliceBidirContract;
+  /** Portability gate — feeds the forbidden-terms audit. */
+  generalization?: SliceGeneralization;
 }

package/lib/contract-validate.ts

@@ -86,54 +86,45 @@ export function validateConvex(c: SliceContract): void {
   }
 }
 
-export function validateBidir(c: SliceContract): void {
-  if (c.bidir === undefined) return;
-  if (!c.bidir || typeof c.bidir !== "object") {
-    throw new Error(`defineSliceContract(${c.id}): bidir must be an object`);
-  }
-  const policies = ["auto-pr", "notify", "manual", "frozen"];
-  if (!policies.includes(c.bidir.syncPolicy)) {
-    throw new Error(
-      `defineSliceContract(${c.id}): bidir.syncPolicy "${String(c.bidir.syncPolicy)}" must be one of ${policies.join("|")}`,
-    );
-  }
-  if (!c.bidir.generalization || typeof c.bidir.generalization !== "object") {
+export function validateGeneralization(c: SliceContract): void {
+  if (c.generalization === undefined) return;
+  if (!c.generalization || typeof c.generalization !== "object") {
     throw new Error(
-      `defineSliceContract(${c.id}): bidir.generalization must be an object`,
+      `defineSliceContract(${c.id}): generalization must be an object`,
     );
   }
   const levels = ["portable", "needs-adapter", "consumer-locked"];
-  if (!levels.includes(c.bidir.generalization.level)) {
+  if (!levels.includes(c.generalization.level)) {
     throw new Error(
-      `defineSliceContract(${c.id}): bidir.generalization.level "${String(c.bidir.generalization.level)}" must be one of ${levels.join("|")}`,
+      `defineSliceContract(${c.id}): generalization.level "${String(c.generalization.level)}" must be one of ${levels.join("|")}`,
     );
   }
-  const ft = c.bidir.generalization.forbiddenTerms;
+  const ft = c.generalization.forbiddenTerms;
   if (ft !== undefined) {
     if (!Array.isArray(ft)) {
       throw new Error(
-        `defineSliceContract(${c.id}): bidir.generalization.forbiddenTerms must be an array`,
+        `defineSliceContract(${c.id}): generalization.forbiddenTerms must be an array`,
       );
     }
     for (const t of ft) {
       if (typeof t !== "string" || t.length === 0) {
         throw new Error(
-          `defineSliceContract(${c.id}): bidir.generalization.forbiddenTerms entries must be non-empty strings`,
+          `defineSliceContract(${c.id}): generalization.forbiddenTerms entries must be non-empty strings`,
         );
       }
     }
   }
-  const rp = c.bidir.generalization.requiredProps;
+  const rp = c.generalization.requiredProps;
   if (rp !== undefined) {
     if (!Array.isArray(rp)) {
       throw new Error(
-        `defineSliceContract(${c.id}): bidir.generalization.requiredProps must be an array`,
+        `defineSliceContract(${c.id}): generalization.requiredProps must be an array`,
       );
     }
     for (const p of rp) {
       if (typeof p !== "string" || p.length === 0) {
         throw new Error(
-          `defineSliceContract(${c.id}): bidir.generalization.requiredProps entries must be non-empty strings`,
+          `defineSliceContract(${c.id}): generalization.requiredProps entries must be non-empty strings`,
         );
       }
     }

package/lib/contract.ts

@@ -13,7 +13,7 @@ import {
   validateHeader,
   validateRbac,
   validateConvex,
-  validateBidir,
+  validateGeneralization,
   validateConflicts,
 } from "./contract-validate";
 
@@ -24,10 +24,8 @@ export type {
   ConvexNamespace,
   SliceContractRequires,
   SliceContractProvides,
-  SliceSyncPolicy,
   GeneralizationLevel,
   SliceGeneralization,
-  SliceBidirContract,
   SliceContract,
 } from "./contract-types";
 
@@ -62,7 +60,7 @@ export function defineSliceContract(c: SliceContract): SliceContract {
   validateHeader(c);
   validateRbac(c);
   validateConvex(c);
-  validateBidir(c);
+  validateGeneralization(c);
   validateConflicts(c);
   return c;
 }

package/lib/manifest.json

@@ -2084,12 +2084,12 @@
       "slug": "rate-limit",
       "title": "Rate Limit",
       "category": "infra",
-      "description": "Convex-backed per-key request counter. Atomic check-and-increment via `consume` mutation; expired rows pruned by `_pruneExpired` internalMutation wired to a 5-min cron. Replaces single-replica in-memory Map so multi-replica Next deployments share buckets. Caller chooses key namespace (csp:<ip>, mcp:<ip>, oauth_token:<ip>). Lifted 2026-05-16 from rahmanef.com.",
+      "description": "Convex-backed per-key request counter. Atomic check-and-increment via `consume` mutation; expired rows pruned by `_pruneExpired` internalMutation wired to a 5-min cron. Replaces single-replica in-memory Map so multi-replica Next deployments share buckets. Limits live in an in-code POLICY map keyed by namespace prefix (admin-login:<ip>, mcp:<ip>) — never caller-supplied; optional RATE_LIMIT_SERVER_KEY env gates anonymous calls. Lifted 2026-05-16 from rahmanef.com; hardened 2026-06-07.",
       "source": "rahmanef.com",
       "install": "npx rahman-resources add rate-limit",
       "npmPackages": [],
       "exampleCode": "",
-      "agentRecipe": "Run `npx rr add rate-limit`. Compose `rateLimitTables` into root convex/schema.ts. Wire `internal.features.rate_limit.mutations._pruneExpired` into convex/crons.ts every 5 min. Call `api.features.rate_limit.mutations.consume({ key, limit, windowMs })` from server-side handlers — keep a fail-open wrapper so a Convex outage doesn't 503 the route.",
+      "agentRecipe": "Run `npx rr add rate-limit`. Compose `rateLimitTables` into root convex/schema.ts. Wire `internal.features.rate_limit.mutations._pruneExpired` into convex/crons.ts every 5 min. Add your namespace to the in-code POLICY map, then call `api.features.rate_limit.mutations.consume({ key, serverKey })` from server-side handlers — keep a fail-open wrapper so a Convex outage doesn't 503 the route. Set RATE_LIMIT_SERVER_KEY on the deployment to block anonymous consume calls.",
       "tags": [
         "infra",
         "rate-limit",
@@ -2634,6 +2634,26 @@
         "basics"
       ]
     },
+    {
+      "slug": "loading-states",
+      "title": "Loading States — skeletons + spinners SSOT",
+      "category": "ui",
+      "description": "Configurable LoadingSkeleton composing the shadcn Skeleton primitive: kind presets text / card / list / table / form / page / block with overridable count + columns. Spinner-based LoadingState (inline / block / overlay) covers in-flight work where a skeleton would be wrong. The page kind drops straight into a route loading.tsx (recipe in README).",
+      "source": "rr original",
+      "install": "npx rahman-resources add loading-states",
+      "npmPackages": [],
+      "exampleCode": "",
+      "agentRecipe": "Run `npx rr add loading-states`. Pick the LoadingSkeleton kind that mirrors the streamed content (<LoadingSkeleton kind=\"table\" count={8} />); use kind=\"page\" inside route loading.tsx. For in-flight work (submits, refetches) use <LoadingState variant=\"inline|block|overlay\" /> instead of a skeleton.",
+      "tags": [
+        "loading",
+        "skeleton",
+        "spinner",
+        "suspense",
+        "fallback",
+        "placeholder",
+        "basics"
+      ]
+    },
     {
       "slug": "marketing-chrome",
       "title": "Marketing Chrome — Header + Footer",
@@ -2700,7 +2720,7 @@
       "title": "Image Editor — layered raster editor",
       "category": "os",
       "kind": "ui",
-      "version": "2.0.1",
+      "version": "2.0.2",
       "description": "A Photoshop-style raster image editor built on Konva. Layers panel (reorder, opacity, visibility, lock, 16 blend modes), free transform (move/scale/rotate/flip via a Transformer), image + text + shape + paint layers, brush & eraser with size/opacity/hardness, non-destructive adjustments + filters, canvas resize/aspect presets, and LAYER STYLES: stroke, drop shadow, outer glow, clipping mask. One-click BACKGROUND REMOVAL runs fully in-browser via @imgly/background-removal (free, no API key — downloads a small ONNX model on first use). Undo/redo, zoom/pan, shortcuts, PNG/JPG/WebP export. v2 adds an AI FUNCTION-CALLING layer: every editor operation is a named, schema'd command (EDITOR_COMMANDS registry + useEditorCommands binding) driven by an in-editor chat; the streaming bridge is injectable via configureAgentStream(fn) and everything except the chat works without it. A headless server barrel (server.ts) runs commands against documents with no DOM. Image I/O via props (initialImage / onSave).",
       "source": "rahmanef63/os-vps",
       "slicePath": "frontend/slices/image-editor",
@@ -2748,7 +2768,7 @@
       "title": "Reel — video timeline editor",
       "category": "os",
       "kind": "ui",
-      "version": "1.0.1",
+      "version": "1.0.2",
       "description": "A complete in-browser video editor. Real media clips (image/video/audio) on a layered multi-track timeline — the top row renders frontmost, with ▲▼ reorder and per-track lock/hide/mute. ONE Canvas-2D draw path is shared by the live preview and the realtime MediaRecorder exporter, so what you see is exactly what renders (WebM with real mixed audio: per-clip volume/fades/auto-duck through a streaming audio graph). Per-clip trim/speed (0.25–4×)/reverse, dissolve/wipe/slide transitions via clip overlap, keyframes (opacity/scale/x/y/rotation) with easing + one-click In/Out animation presets, text styling with preset grid, color grading + vignette, filmstrip thumbnails + real waveforms, snapping, split/duplicate. The workspace is config-driven: 6 resizable layout presets (react-resizable-panels v4) incl. quick-import files-pane layouts, plus custom composition size. Drafts auto-save to localStorage. Self-contained: toasts via sonner, the files pane runs on an injectable fs adapter (configureReelFs; in-memory mock by default), and shell hooks (inspector/activity) are inert seams in lib/host.ts.",
       "source": "rahmanef63/os-vps",
       "slicePath": "frontend/slices/reel-editor",
@@ -2826,7 +2846,7 @@
       "title": "Code — overlay syntax editor",
       "category": "os",
       "kind": "ui",
-      "version": "1.0.1",
+      "version": "1.0.2",
       "description": "A lightweight code editor in the VS-Code spirit without the weight: a transparent textarea layered over a highlighted pre (regex tokenizer for JS/TS/JSON/CSS) gives real editing with live syntax color and a line-number gutter; a tab strip tracks dirty buffers with Cmd/Ctrl+S save; a status bar shows path, Ln/Col, tab size, language and save state. The explorer is a lazy per-directory tree — each folder lists on expand, with inline new-file/new-folder affordances — rendered as a rail on desktop and a Sheet on mobile, and the new-file form is a responsive dialog ⇄ bottom drawer. The filesystem is INJECTED via a small CodeFsAdapter (list/read/write/mkdir): point configureCodeFs at a real API or use the bundled writable in-memory mock (seeded sample tree) so it works with zero backend. Writes are best-effort — a read-only host flags the save but keeps the local buffer. Pairs with file-explorer (onOpenFile → payload) and appshell.",
       "source": "rahmanef63/os-vps",
       "slicePath": "frontend/slices/code-editor",
@@ -2957,7 +2977,7 @@
       "title": "Browser — remote headless-browser chrome",
       "category": "os",
       "kind": "ui",
-      "version": "1.0.1",
+      "version": "1.0.2",
       "description": "Full browser chrome for a REMOTE headless browser: omnibar with search-or-URL detection, bookmark bar, history view (localStorage-persisted), favicons with globe fallback, busy states, and a screenshot viewport that forwards clicks/typing/keys/scroll into the remote page. The backend is INJECTED via a small BrowserAdapter (state/screenshot/act): point configureBrowser at a real headless-Chromium service (e.g. Playwright behind an authed route — any site renders, no X-Frame-Options problem) or keep the bundled offline canvas demo renderer that fakes the viewport so the whole chrome works with zero backend. Self-contained: shell inspector hooks are inert seams in lib/host.ts.",
       "source": "rahmanef63/os-vps",
       "slicePath": "frontend/slices/browser",
@@ -3063,7 +3083,7 @@
       "title": "AppShell — Desktop + Mobile OS Shell",
       "category": "os",
       "kind": "full",
-      "version": "1.2.1",
+      "version": "1.3.1",
       "description": "Generic, brand-free OS-style shell framework. One <AppShell manifest> wrapper provider gives a project a macOS-style window manager (drag/snap/maximize, dock, menu bar, Spotlight) AND an iOS-style mobile surface (home pager, app library, control center, widgets), driven entirely by a manifest: brand, apps, features, surface regions, capabilities, persistence, keymap. Five shell features (search, inspector, notifications, control-center, widgets) are bundled as defineFeature() contributions inside the slice and mount via named <Slot>s. Responsiveness is a single ResponsiveProvider + 4 DRY primitives (AppFrame, MasterDetail, ResponsiveToolbar, TouchList). Imports nothing project-specific — the consumer injects data/auth/AI through manifest.capabilities. Lifted from os-vps (Topside).",
       "source": "rahmanef63/os-vps",
       "slicePath": "frontend/slices/appshell",
@@ -4135,8 +4155,8 @@
       "title": "Rate Limit",
       "category": "infra",
       "kind": "backend",
-      "version": "0.1.0",
-      "description": "Convex-backed per-key request counter. Atomic check-and-increment via `consume` mutation; expired rows pruned by `_pruneExpired` internalMutation wired to a 5-min cron. Replaces single-replica in-memory Map so multi-replica Next deployments share buckets. Caller chooses key namespace (csp:<ip>, mcp:<ip>, oauth_token:<ip>). Lifted 2026-05-16 from rahmanef.com.",
+      "version": "0.2.0",
+      "description": "Convex-backed per-key request counter. Atomic check-and-increment via `consume` mutation; expired rows pruned by `_pruneExpired` internalMutation wired to a 5-min cron. Replaces single-replica in-memory Map so multi-replica Next deployments share buckets. Limits live in an in-code POLICY map keyed by namespace prefix (admin-login:<ip>, mcp:<ip>) — never caller-supplied; optional RATE_LIMIT_SERVER_KEY env gates anonymous calls. Lifted 2026-05-16 from rahmanef.com; hardened 2026-06-07.",
       "source": "rahmanef.com",
       "slicePath": "frontend/slices/rate-limit",
       "convexPaths": [
@@ -4154,7 +4174,7 @@
         "backend",
         "throttle"
       ],
-      "agentRecipe": "Run `npx rr add rate-limit`. Compose `rateLimitTables` into root convex/schema.ts. Wire `internal.features.rate_limit.mutations._pruneExpired` into convex/crons.ts every 5 min. Call `api.features.rate_limit.mutations.consume({ key, limit, windowMs })` from server-side handlers — keep a fail-open wrapper so a Convex outage doesn't 503 the route."
+      "agentRecipe": "Run `npx rr add rate-limit`. Compose `rateLimitTables` into root convex/schema.ts. Wire `internal.features.rate_limit.mutations._pruneExpired` into convex/crons.ts every 5 min. Add your namespace to the in-code POLICY map, then call `api.features.rate_limit.mutations.consume({ key, serverKey })` from server-side handlers — keep a fail-open wrapper so a Convex outage doesn't 503 the route. Set RATE_LIMIT_SERVER_KEY on the deployment to block anonymous consume calls."
     },
     {
       "slug": "testimonials",
@@ -5135,6 +5155,35 @@
       ],
       "agentRecipe": "Run `npx rr add empty-states`. Drop <EmptyState kind=\"no-results\" /> into zero-data spots; wrap with <ErrorPage kind=\"404\" /> in app/not-found.tsx and kind=\"500\" in app/error.tsx. Every preset's icon/title/description/action overridable per use."
     },
+    {
+      "slug": "loading-states",
+      "title": "Loading States — skeletons + spinners SSOT",
+      "category": "ui",
+      "kind": "ui",
+      "version": "0.1.0",
+      "description": "Configurable LoadingSkeleton composing the shadcn Skeleton primitive: kind presets text / card / list / table / form / page / block with overridable count + columns. Spinner-based LoadingState (inline / block / overlay) covers in-flight work where a skeleton would be wrong. The page kind drops straight into a route loading.tsx (recipe in README).",
+      "source": "rr original",
+      "slicePath": "frontend/slices/loading-states",
+      "convexPaths": [],
+      "npm": [],
+      "shadcn": [
+        "skeleton",
+        "spinner"
+      ],
+      "env": [],
+      "peers": [],
+      "providers": [],
+      "tags": [
+        "loading",
+        "skeleton",
+        "spinner",
+        "suspense",
+        "fallback",
+        "placeholder",
+        "basics"
+      ],
+      "agentRecipe": "Run `npx rr add loading-states`. Pick the LoadingSkeleton kind that mirrors the streamed content (<LoadingSkeleton kind=\"table\" count={8} />); use kind=\"page\" inside route loading.tsx. For in-flight work (submits, refetches) use <LoadingState variant=\"inline|block|overlay\" /> instead of a skeleton."
+    },
     {
       "slug": "marketing-chrome",
       "title": "Marketing Chrome — Header + Footer",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rahman-resources",
-  "version": "1.12.0",
-  "description": "Rahman Resources (rr) \u2014 shadcn-style installer for vertical slices. `npx resources add <slug>` copies slice into your project's `slices/<slug>/`. You own the files.",
+  "version": "1.13.0",
+  "description": "Rahman Resources (rr) — shadcn-style installer for vertical slices. `npx resources add <slug>` copies slice into your project's `slices/<slug>/`. You own the files.",
   "type": "module",
   "license": "MIT",
   "author": "Rahman <casadezian@gmail.com>",