@fugood/bricks-ctor 2.25.0-beta.60 → 2.25.0-beta.61

package/skills/bricks-ctor/references/remote-data-bank.md

@@ -1,196 +0,0 @@
-# Remote Data Bank
-
-Cloud-synchronized Data Bank for real-time data sharing across devices and external API access.
-
-## Remote Update Types
-
-The `remoteUpdate` field configures cloud synchronization:
-
-```typescript
-remoteUpdate?:
-  | { type: 'auto' }           // Sync across all devices
-  | { type: 'device-specific' } // Isolated per device
-  | { type: 'global-data', id: string } // Cross-application global data
-```
-
-### Auto Sync
-
-Sync across all devices using the same application.
-
-```typescript
-import { makeId } from 'bricks-ctor'
-
-const data: Data = {
-  __typename: 'Data',
-  id: makeId('data'),
-  title: 'Announcement',
-  type: 'string',
-  value: '',
-  remoteUpdate: { type: 'auto' },
-  events: {},
-}
-```
-
-### Global Data
-
-Share data across different applications. Must create Global Data first on BANK page.
-
-```typescript
-import { makeId } from 'bricks-ctor'
-
-const data: Data = {
-  __typename: 'Data',
-  id: makeId('data'),
-  title: 'Global Config',
-  type: 'object',
-  value: {},
-  remoteUpdate: { type: 'global-data', id: 'workspace-global-config-id' },
-  events: {},
-}
-```
-
-### Device Specific
-
-Isolate data per device while still allowing web page control.
-
-```typescript
-import { makeId } from 'bricks-ctor'
-
-const data: Data = {
-  __typename: 'Data',
-  id: makeId('data'),
-  title: 'Device Message',
-  type: 'string',
-  value: '',
-  remoteUpdate: { type: 'device-specific' },
-  events: {},
-}
-```
-
-Use case: Control individual displays from a shared web interface without affecting other devices.
-
-## External Access
-
-### Web Update Page
-
-Generate a web page for non-technical users to update data:
-
-1. Visit BANK page
-2. Click `Manage Keys`
-3. Select `Generate Key used by Update Page`
-4. Share the generated link
-
-The page has independent permissions and can be shared with content managers.
-
-### API Access
-
-Programmatic data updates via REST API.
-
-**Setup:**
-1. Visit BANK page → Manage Keys
-2. Create API key with appropriate permissions
-3. Use key in API requests
-
-**Example API Usage:**
-
-```bash
-# Update a property
-curl -X POST https://api.bricks.tools/v1/bank/update \
-  -H "Authorization: Bearer YOUR_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "applicationId": "app-id",
-    "propertyId": "announcement",
-    "value": "New announcement text"
-  }'
-
-# Get property value
-curl https://api.bricks.tools/v1/bank/get \
-  -H "Authorization: Bearer YOUR_API_KEY" \
-  -G \
-  -d "applicationId=app-id" \
-  -d "propertyId=announcement"
-```
-
-## Data Routing
-
-Cross-subspace data sharing with access control.
-
-```typescript
-const routedData: Data = {
-  __typename: 'Data',
-  id: 'shared-state',
-  type: 'object',
-  routing: 'read-only', // 'read-only' | default (read-write)
-  // When read-only: only accepts changes from same subspace
-  // Default: accepts changes from any subspace
-}
-```
-
-## Use Cases
-
-### Digital Signage Content Management
-
-```typescript
-import { makeId } from 'bricks-ctor'
-
-// Remote-updated announcement
-const announcement: Data = {
-  __typename: 'Data',
-  id: makeId('data'),
-  title: 'Announcement',
-  type: 'object',
-  value: { title: '', body: '', enabled: false },
-  remoteUpdate: { type: 'auto' },
-  events: {},
-}
-```
-
-Operator updates content via web page → All displays update in real-time.
-
-### Multi-Location Coordination
-
-```typescript
-import { makeId } from 'bricks-ctor'
-
-// Global data shared across locations
-const globalConfig: Data = {
-  __typename: 'Data',
-  id: makeId('data'),
-  title: 'Brand Config',
-  type: 'object',
-  value: {},
-  remoteUpdate: { type: 'global-data', id: 'brand-config-global' },
-  events: {},
-}
-```
-
-Update once → All locations receive update.
-
-### Per-Device Customization
-
-```typescript
-import { makeId } from 'bricks-ctor'
-
-// Device-specific greeting
-const deviceGreeting: Data = {
-  __typename: 'Data',
-  id: makeId('data'),
-  title: 'Greeting',
-  type: 'string',
-  value: '',
-  remoteUpdate: { type: 'device-specific' },
-  events: {},
-}
-```
-
-Each display shows different greeting, controlled from single dashboard.
-
-## Best Practices
-
-1. **Minimize remote data**: Only enable for data that truly needs cloud sync
-2. **Use device-specific wisely**: Good for personalization, not for shared state
-3. **API key security**: Use scoped keys with minimal permissions
-4. **Offline resilience**: Design for temporary disconnection
-5. **Batch updates**: Group related changes to reduce API calls
-6. **Global data governance**: Establish clear ownership for global data keys

package/skills/bricks-ctor/references/simulator.md

@@ -1,132 +0,0 @@
-# Simulator
-
-What the Simulator can and can't faithfully reproduce — so a passing Simulator run means what you think it means. This is the fidelity companion to Path 1 in [Verification Toolchain](verification-toolchain.md); read that for how to *drive* the Simulator (compile, screenshot, Automations).
-
-## What it is
-
-- The default Path 1 target: it renders your compiled project on your computer, with no device required.
-- It runs in Chromium/Electron — a browser-class runtime, not the device runtime. Two consequences to design verification around: it has a browser's capabilities and limits (below), and its JavaScript engine differs from the device's (iOS runs JSC, Android runs Hermes), so engine-specific behavior won't surface here.
-
-A Simulator screenshot proves **layout, navigation, Standby Transitions, Data wiring, and generator/Automation wiring**. It does *not* prove anything that depends on real hardware, real models, or capabilities the preview runtime lacks.
-
-## Automation screenshots
-
-`match_screenshot` stores Simulator automation artifacts at the project level:
-
-```text
-.bricks/automation_screenshots/
-  last/
-  failed/
-  diff/
-```
-
-There is no application-id subdirectory; in CTOR the project is the application. Generated project `.gitignore` files exclude this directory.
-
-When a `match_screenshot` baseline is missing or updated, the baseline goes under `last/`. When a screenshot mismatch occurs, the current capture goes under `failed/` and the pixel diff goes under `diff/`. File names follow `<screenshotName>+local+<timestamp>.png`.
-
-In CTOR Desktop, `simulator_invoke` reports any automation screenshot files created or changed by the invocation in an `Automation screenshots:` section. It still separately reports the ordinary preview capture at `.bricks/simulator-screenshot.jpg`.
-
-## What the Simulator can't reproduce
-
-Because it runs in a browser-class preview rather than on device hardware, the Simulator cannot exercise these — a green run says nothing about them. Verify on a real device (Path 2):
-
-| Area | In the Simulator |
-|------|------------------|
-| BLE (Central / Peripheral), Video Streaming | Not available |
-| Raw network sockets — UDP, TCP, TCP Server, MQTT Broker | Not available (also why Buttress LAN discovery is a no-op — see [Buttress](buttress.md)) |
-| Android Intent | Not available (Android-only) |
-| On-device database **persistence** (SQLite / Vector Store) | Not available — both run in-memory in the Simulator (see caveats below), so data never survives a reload |
-| GGML Text-to-Speech | No vocoder in the preview — use an ONNX TTS model to hear speech |
-
-These work, but with browser caveats:
-
-| Area | Caveat |
-|------|--------|
-| Serial Port | Works via WebSerial — requires browser support and a user gesture |
-| WebView / WebCrawler | Subject to browser CORS — a load/fetch that works on device may be blocked |
-| On-device AI (LLM / STT / VAD / Vector Store / Reranker) | Runs **single-threaded** — far slower than the device, not representative of real latency. Also subject to the model fallbacks below |
-| On-device database (SQLite — `GENERATOR_SQLITE`) | Runs for real on the in-memory WASM `sqlite-vec` build — `execute` / `query` / `transaction` / batch all work. `storageType: file` is transparently treated as in-memory, so nothing persists across reloads (see above) |
-| Scene3D / Sketch / WebRTC | Supported |
-
-Feature availability also varies across the device platforms themselves (iOS / tvOS / Android / the desktop OSes). When a deployment targets a specific platform's capability, confirm it on that platform.
-
-## Network security
-
-The Simulator blocks insecure connections from `applicationPreview` by default: `http://` and `ws://` requests fail, while `https://` and `wss://` are allowed. The Simulator internally allows its own preview host when running the development preview.
-
-Generated projects include this project-level setting:
-
-```json
-{
-  "allowedInsecureHosts": []
-}
-```
-
-Add explicit entries only when you deliberately need to test an insecure endpoint in the Simulator. A bare `host:port` allows both `http://` and `ws://` for that host:
-
-```json
-{
-  "allowedInsecureHosts": ["localhost:8080"]
-}
-```
-
-Use a URL form when only one insecure protocol should be allowed:
-
-```json
-{
-  "allowedInsecureHosts": ["http://localhost:8080"]
-}
-```
-
-In that example, `http://localhost:8080` is allowed and `ws://localhost:8080` remains blocked.
-
-Prefer HTTPS/WSS for anything that is not local development.
-
-## Feature fallbacks — what the Simulator fakes
-
-So that camera and AI features are usable without device permissions, multi-gigabyte downloads, API keys, or a remote inference backend, the Simulator **transparently substitutes a lightweight stand-in** for a few bricks/generators. The config you author is untouched — only the Simulator's runtime behavior differs. **A fallback render proves wiring and layout, not the real feature.**
-
-| Brick / Generator | In the Simulator | Does NOT prove |
-|-------------------|------------------|----------------|
-| Camera (`BRICK_CAMERA`) | A 3D mock canvas, no camera permission prompt. `takePicture` snapshots the canvas; recording produces a placeholder clip | Real camera feed, focus, recording, permission flow |
-| Maps (`BRICK_MAPS`) | A real interactive map on free OpenStreetMap-based tiles — no Google Maps API key needed. Markers, path polyline, the six themes / map types (approximated with free tile sets + CSS tints), and the zoom / pan / navigate / focus / reset / fit actions all work | Google / Apple Maps rendering, exact `customMapStyle` / theme styling (approximated), traffic / buildings / indoors layers, real device geolocation |
-| Thermal Printer (`GENERATOR_THERMAL_PRINTER`) | A simulated printer — `init` / `checkStatus` / `scan` fake per-driver status and discovered devices (ESC/POS, Star, TSC, Castles); `print` renders an approximate on-screen receipt. A bottom-left bubble shows live status with a fault toggle to exercise error wiring. Print results can be exported as PNG via `bricks-cli` (see below) | Real device connection, actual paper output, exact native driver status codes |
-| LLM (`GENERATOR_LLM`) | Swapped to a tiny local stand-in model | Output quality / latency of your real model |
-| Reranker — GGML (`GENERATOR_RERANKER`) | Swapped to a small local multilingual reranker model | Ranking quality / latency of your real model |
-| Speech-to-Text — GGML (`GENERATOR_SPEECH_INFERENCE`) | Swapped to a tiny local model | Accuracy / latency of your real model |
-| Speech-to-Text — ONNX (`GENERATOR_ONNX_STT`) | Swapped to a tiny whisper model | Accuracy / latency of your real model |
-| Text-to-Speech — ONNX (`GENERATOR_TTS`) | Swapped to a tiny VITS model (no vocoder or speaker embedding) | Voice / quality / latency of your real model |
-| Vector Store (`GENERATOR_VECTOR_STORE`) | Runs with a tiny local embedding model — an OpenAI-source config works **without a key** | Real embeddings / dimensions / recall (and no persistence — see above) |
-| Buttress (all generators) | **Disabled** — there is no remote inference backend in the Simulator | The Buttress offload path — see [Buttress](buttress.md) |
-| MLX LLM (`GENERATOR_MLX_LLM`) | Runs as authored, except Buttress is disabled | The MLX / Buttress path |
-
-These swaps make the AI generators runnable in the Simulator for wiring checks — validate real models, quality, and latency on a device (Path 2).
-
-### Inspecting simulated thermal printer print results
-
-With the Simulator running (CDP at `localhost:19852`, see [Verification Toolchain](verification-toolchain.md)), `bricks-cli` can read the simulated printers and export a print result as a PNG image — no need to open the bubble popover or screenshot the whole window:
-
-```bash
-# Printers + print history (newest first; shows the --index value per result)
-bricks devtools simulator thermal-printer list -p 19852
-bricks devtools simulator thermal-printer list -p 19852 -j --commands   # full print payloads as JSON
-
-# Render one print result to PNG (defaults: the only printer, --index 0 = latest)
-bricks devtools simulator thermal-printer print-result -p 19852 -o receipt.png
-bricks devtools simulator thermal-printer print-result -p 19852 --index 1 --scale 2 -o older.png
-```
-
-The PNG is the same approximate receipt the on-screen preview shows (rendered from the print payload). It proves the payload wiring — content, ordering, alignment, barcode/QR/image presence — not pixel-exact native raster output. Print history is in-memory (up to 10 per printer) and clears on preview reload.
-
-### Running the real implementation instead
-
-Each substituted brick/generator can be switched back to its real implementation per item: open the **gear (Simulator settings)** in the editor's preview toolbar, uncheck the item, and **Apply**. Apply persists the choice and reloads the preview so it takes effect (a plain refresh won't). Use this to, e.g., point a Vector Store at a real API key in the preview, or render the real Google/Apple Maps brick (which needs a Maps API key on web). The browser limits above still apply, and **Buttress stays disabled regardless** — there's no backend for it here.
-
-The Thermal Printer is the exception: it has no real web implementation to switch to (the native drivers can't run in a browser), so it is **always simulated** and is not in the gear list.
-
-## Enough vs. escalate
-
-- **Simulator is enough for:** layout, navigation, Standby Transitions, Data wiring, Automation / state-machine happy paths, and confirming a generator fires and handles its events.
-- **Escalate to a real device for:** anything in the "can't reproduce" tables, real camera / peripherals / payment / identity, real model quality & latency, multi-device Local Sync, on-device persistence, the Buttress offload path, and engine-specific behavior.
-
-The full Path 1/2/3 decision rule lives in [Verification Toolchain](verification-toolchain.md).

package/skills/bricks-ctor/references/source-editing-tools.md

@@ -1,81 +0,0 @@
-# MCP Source-Editing Tools
-
-The project-local `bricks-ctor` MCP server exposes tools that edit `subspaces/**` via
-surgical AST edits, keeping files in the standard generated style. Prefer them over
-hand-editing entry files; they validate references, manage imports, compile-verify, and
-record every operation in `.bricks/edits.jsonl`.
-
-## Entry tools (bricks.ts / generators.ts / canvases.ts / data.ts / animations.ts)
-
-| Tool | Purpose |
-|------|---------|
-| `new_entry` | Create a standard entry skeleton (`file`, `type`, `templateKey`, `alias`, optional initial `set`/`events`) |
-| `edit_entry` | Set/unset dotted paths on an entry: `title`, `property.url`, `outlets.response`, `value`, `switches[0].property.text`, … |
-| `edit_events` | Add/remove/replace/move/clear EventAction items in `events.<eventKey>` |
-| `edit_canvas_items` | Add/replace/remove/move brick items on a Canvas `items` array (frames need numeric x/y/width/height) |
-| `edit_switches` | Add/replace/remove/move switches (id, title, conds, override, disabled, break) |
-| `remove_entry` | Delete an entry; cascades same-subspace references by default, `strict: true` refuses and lists sites |
-
-Addressing: `{ file, entry }` (export const name) is primary; `id` works as a global
-fallback (omit `file`). `edit_entry`/`edit_events` accept a `switch` parameter (switch id
-or index) to edit the facets inside one switch — `edit_switches` owns only the array and
-the conds/override shell.
-
-### Event actions
-
-```jsonc
-{
-  "handler": "system",            // or { "ref": "brickOrGeneratorRef" } or { "subspace": "SUBSPACE_id" }
-  "name": "CHANGE_CANVAS",
-  "params": { "canvasId": { "ref": "mainCanvas" } },   // template params, OR:
-  "dataParams": { "someData": 5 },                      // PROPERTY_BANK-style params
-  "waitAsync": false
-}
-```
-
-System actions derive their `as SystemAction...` cast automatically; entity-action casts
-are added only when passed via `cast`. The compiled source form
-`{ handler, action: { name, params: [...], dataParams: [...] }, waitAsync }` is also
-accepted, and `{ "expr": "<raw EventAction>" }` is the escape hatch for shapes the
-structured form cannot express. Handler refs must resolve to a brick or generator.
-`PROPERTY_BANK_EXPRESSION` expressions are validated against the runtime fold rules at
-edit time: only expression statements, simple `const`/`let` declarations, and a final
-return inside a zero-arg IIFE evaluate — no `if`/`for`/`while` (use ternaries, or a
-DataCalculationScript for branching logic).
-
-## Data-calc tools (DataCalculationScript only)
-
-| Tool | Purpose |
-|------|---------|
-| `new_data_calc` | Create `data-calc/data-calculation-{slug}.ts` + `.sandbox.js`, regenerate `data-calc/index.ts`, wire a minimal subspace root |
-| `edit_data_calc` | Set/unset scalar fields, `output`/`error` refs, replace whole `inputs`/`outputs`, or rewrite the sandbox `code` |
-| `edit_data_calc_io` | Add/remove/replace/clear single `inputs`/`outputs` items (input keys unique; output keys may repeat for fan-out) |
-| `remove_data_calc` | Delete the calc `.ts` + its sandbox file and regenerate the index |
-
-Addressing: `{ file }` or `{ subspace, calc }` where `calc` is alias, id, or filename
-slug (subspace defaults to `subspace-0`). Code is canonicalized to the sandbox file form
-(`export function main() { ... }` — wrapped automatically, `async` added when the body
-uses top-level `await`). `DataCalculationMap` (visual node graph) is out of scope and
-returns `fallback_recommended`.
-
-## Value grammar (everywhere a value appears)
-
-| You pass | Emits |
-|----------|-------|
-| JSON scalar/array/object | literal |
-| `{ "link": "dataRefOrAlias" }` | `linkData(() => data.dX)` (property data-links) |
-| `{ "ref": "idOrAliasOrVarName", "subspace"?: 1 }` | `() => namespace.varName` getter |
-| `{ "expr": "raw TypeScript" }` | spliced verbatim |
-
-References resolve by var name, id, or alias within the target subspace and fail loudly
-when missing or ambiguous — this doubles as reference validation.
-
-## Verification and audit
-
-- Every call compile-verifies by default and returns `verify.configChange` — the minimal
-  compiled-config delta (path-keyed set/unset ops). Skip with per-call `verify: false`
-  or `BRICKS_CTOR_MCP_EDIT_VERIFY=0` when batching, then finish with the `compile` tool.
-- All operations append to `.bricks/edits.jsonl` (gitignored) with inputs, outcomes, and
-  touched sites.
-- Non-standard files or entries (hand-written shapes the AST editor cannot safely
-  rewrite) return `fallback_recommended` — use plain file edits for those cases only.

package/skills/bricks-ctor/references/standby-transition.md

@@ -1,124 +0,0 @@
-# Standby Transition
-
-Easy-to-configure animation for Bricks based on Canvas render/change. Provides smooth enter animations when bricks appear and position transitions when canvas changes.
-
-## How It Works
-
-Two transition cases:
-1. **First Render**: Run position transition based on `standbyMode` setting
-2. **Canvas Change**: Existing bricks animate to new positions instead of re-rendering
-
-## Configuration
-
-Standby transition is configured in the **canvas item frame**, not the brick itself.
-
-### Standby Mode
-
-| Mode | Description |
-|------|-------------|
-| `top` | Slide in from top |
-| `bottom` | Slide in from bottom |
-| `left` | Slide in from left |
-| `right` | Slide in from right |
-| `custom` | Use custom `standbyFrame` values |
-
-### Frame Options
-
-| Option | Description |
-|--------|-------------|
-| `standbyMode` | Direction or `'custom'` |
-| `standbyFrame` | Custom start frame `{ x?, y?, width?, height? }` |
-| `standbyOpacity` | Start opacity (0.0 - 1.0) |
-| `standbyDelay` | Delay before transition starts (ms) |
-| `standbyDelayRandom` | Random delay variance (ms) |
-| `standbyEasing` | Per-property easing config |
-
-### Easing Configuration
-
-```typescript
-standbyEasing: {
-  default?: { method: Easing, duration: number },
-  x?: { method: Easing, duration: number },
-  y?: { method: Easing, duration: number },
-  width?: { method: Easing, duration: number },
-  height?: { method: Easing, duration: number },
-  opacity?: { method: Easing, duration: number },
-}
-```
-
-## TypeScript Example
-
-```typescript
-import { makeId } from 'bricks-ctor'
-
-const canvas: Canvas = {
-  __typename: 'Canvas',
-  id: makeId('canvas'),
-  title: 'Home',
-  description: '',
-  property: {
-    backgroundColor: '#ffffff',
-  },
-  events: {},
-  switches: [],
-  items: [
-    {
-      item: () => heroCard,
-      frame: {
-        x: 100,
-        y: 50,
-        width: 400,
-        height: 300,
-        // Standby transition config
-        standbyMode: 'bottom',
-        standbyOpacity: 0,
-        standbyDelay: 100,
-        standbyEasing: {
-          default: { method: 'easeOutCubic', duration: 400 },
-          opacity: { method: 'easeOutQuad', duration: 300 },
-        },
-      },
-    },
-  ],
-}
-```
-
-## Canvas Change Transition
-
-When navigating between canvases, bricks with the same ID smoothly transition:
-- Position interpolates from old to new location
-- Size interpolates if dimensions change
-- Opacity interpolates if visibility changes
-
-This creates a "shared element transition" effect.
-
-## Related Events
-
-- `standby`: Triggered when brick completes standby transition
-
-```typescript
-// In brick definition
-events: {
-  standby: [
-    {
-      handler: 'system',
-      action: {
-        __actionName: 'DYNAMIC_ANIMATION',
-        parent: 'System',
-        params: [
-          { input: 'brickId', value: () => heroCard },
-          { input: 'animationId', value: () => pulseAnimation },
-        ],
-      },
-    },
-  ],
-}
-```
-
-## Best Practices
-
-1. **Stagger delays**: Use incremental delays for list items (e.g., 0, 50, 100ms)
-2. **Keep it short**: 200-400ms transitions feel responsive
-3. **Match content**: Use directional transitions that match scroll direction
-4. **Opacity for polish**: Combine position transition with opacity fade
-5. **Same-ID trick**: Reuse brick IDs across canvases for smooth transitions