App Lab

App Lab is a contract-driven demo factory that turns semantic sketches into route-based HTML demos.

This repository is intentionally self-contained with strict layer separation:

• system-layer assets at repo root
• workspace-specific assets under apps/*

Structure For Clarity And Scale

app-lab/
	src/                    # system-layer compiler pipeline
	contracts/              # system-layer schemas, policies, manifests
	skills/                 # reusable workflow playbooks
	docs/                   # system-layer architecture and operations docs
	apps/                   # workspace-specific assets only
		app-manager/
		authentication-flow/

Boundary Contract

System Layer

• src/
• contracts/
• skills/
• docs/

System code must remain generic and must not hardcode workspace details.

Workspace Layer

Each app workspace under apps/* owns:

• sketches/
• layout/
• cst/
• data/
• html/
• docs/
• app.manifest.json
• app/shell/ shell template and css fragments referenced by entrypoints.workspaceShell

Core Rules

1. Root scripts operate by app input (--app <app-id>), not by hardcoded app names.
2. Contracts are authoritative and version-checked.
3. App-specific docs stay in apps/<app>/docs/.
4. Generated artifacts stay local to each workspace.
5. No fallback behavior that blends incompatible schema paths.
6. entrypoints.workspaceShell.template is required for all compile modes.
7. entrypoints.workspaceShell.cssFragments is required for workspace-shell mode.

Sketch Source Of Truth

The approved sketch markdown is the primary source of truth for implementation. Client-side AI assistants must produce sketches in this exact structure so extraction and compile steps remain deterministic.

Required shape:

## <number>) <screen title>

```text
<ASCII screen>

Minimal example:

```text
## 1) Workspace Grid / Fleet Overview

```text
+=================================================================================+
| APPTURE APP MANAGER                                       [Refresh] [Filter v] |
| Workspaces: 18  Running: 11  Stopped: 7  Host CPU: 62%  Host MEM: 71%          |
+=================================================================================+
| [RUNNING] system-dashboard  | [STOPPED] financial-dash  | [RUNNING] ops-observ |
| workspace: apps/system-...  | workspace: apps/finan...  | workspace: apps/ops  |
| version: 1.4.2  p95: 92ms   | version: 0.9.8  p95: --   | version: 2.1.0  p95: |
| [Open] [Stop] [Details]     | [Open] [Start] [Details]  | [Open] [Stop] [Det]  |
+=================================================================================+

Reference examples:

- `apps/app-manager/docs/app-manager.md`
- `apps/authentication-flow/docs/auth-demo.md`

Non-negotiable sketch conventions:

1. Numbered sections (`## 1) ...`, `## 2) ...`) are required.
2. Each section must include exactly one fenced `text` block.
3. Use explicit labels for statuses, metrics, and actions.
4. Keep names stable across screens (`app`, `workspace`, `status`, `p95`, etc.).
5. Include edge/error states in the sketch, not as separate prose.

## Sketch Flexibility

The compiler is intentionally flexible about what kind of screen can be sketched, as long as the section + `text` block contract is respected.

Supported archetypes include:

1. Fleet dashboard with repeated cards.
2. Split-pane grid + metadata drawer.
3. Monitoring console with metrics + logs.
4. Form-driven launch or workflow sequence.
5. Baseline zone map for layout validation.

Example: split-pane (grid + drawer)

```text
## 2) Workspace Grid with Metadata Drawer

```text
+=============================================================================================+
| APPTURE APP MANAGER                                                                         |
+=============================================================================================+
| GRID                                                         | APP DETAILS                  |
|--------------------------------------------------------------|------------------------------|
| [RUNNING] system-dashboard  p95: 92ms  [Open] [Stop]        | app: system-dashboard        |
| [STOPPED] financial-dash    p95: --    [Open] [Start]       | workspace: apps/system-...   |
| [RUNNING] audit-console     p95: 49ms  [Open] [Stop]        | status: RUNNING              |
|                                                              | routes: / /health /metrics   |
|                                                              | [Restart] [Open Workspace]   |
+=============================================================================================+

Example: monitoring console

```text
## 3) Monitoring Screen for Selected App

```text
+==================================================================================================+
| APP MONITOR :: system-dashboard                                   [Open] [Restart] [Stop] [Export] |
+==================================================================================================+
| Status: RUNNING  Health: OK  Port: 3000  Workspace: apps/system-dashboard                         |
+-----------------------------------+------------------------------+----------------------------------+
| PERFORMANCE                        | REQUESTS                     | SYSTEM IMPACT                    |
| CPU 8%  MEM 412MB  THREADS 17      | req/min 340  p95 92ms        | host cpu 5.2%  log rate 184/min  |
+-----------------------------------+------------------------------+----------------------------------+
| 10:42:11 INFO server ready         | 10:42:15 WARN backlog=12     | 10:42:31 INFO recovery complete  |
+==================================================================================================+

Example: flow form

```text
## 4) Browser Launch Detached App Window Flow

```text
+---------------------------------------------------------------------------------------------+
| Launch App in Separate Window                                                               |
+---------------------------------------------------------------------------------------------+
| App: system-dashboard   URL: http://localhost:3000   State: RUNNING                         |
| (o) New browser window   ( ) New tab                                                        |
| [x] Pass workspace context   [x] Emit launch audit event   [ ] Enable write-mode            |
| [Cancel]                                                           [Launch Window]           |
+---------------------------------------------------------------------------------------------+

Example: canonical zone map

```text
## 5) Canonical Baseline Layout

```text
+================================================================================================+
| header / fleet-summary                                                                         |
+================================================================================================+
| workspace-grid                                              | app-detail-drawer               |
| workspace-grid                                              | app-detail-drawer               |
+------------------------------------------------------------------------------------------------+
| monitor-metrics                                             | host-impact                     |
+------------------------------------------------------------------------------------------------+
| log-sniffer                                                 | export-actions                  |
+================================================================================================+

## Ingestion Rules

What the extractor/compiler needs from client AI output:

1. Numbered route sections are mandatory.
2. Exactly one fenced `text` block per section.
3. Stable labels for repeated entities (`app`, `workspace`, `status`, `health`, `p95`, `actions`).
4. Explicit state indicators (`RUNNING`, `STOPPED`, `DEGRADED`, `ERROR`) when stateful behavior exists.
5. Action verbs rendered as bracketed controls (`[Open]`, `[Stop]`, `[Details]`, etc.).

What can vary without breaking ingestion:

1. Overall ASCII geometry.
2. Number of cards/rows/panels.
3. Whether the screen is dashboard-style, form-style, log-style, or topology-style.
4. Depth of textual detail inside each panel.

## Component Vocabulary For Client AI Sketches

Use these ASCII patterns to express component intent clearly.

Inputs and form controls:

```text
Text input:        [ Username: __________________________ ]
Password input:    [ Password: *********************** ]
Search input:      [ Search apps...____________________ ] [Go]
Textarea:          [ Notes:
					| line 1
					| line 2
					]
Checkbox:          [x] Include diagnostics   [ ] Enable write-mode
Radio group:       (o) New window   ( ) New tab   ( ) Embedded pane
Select/dropdown:   [ Environment: dev v ]
Toggle:            [ ON ] Live Refresh

Navigation and actions:

Tabs:              [Overview] [Monitoring] [Launch] [Impact]
Primary action:    [ Launch Window ]
Secondary action:  [Cancel] [Preview] [Export]
Chip/tag:          [runtime] [policy-strict] [signed-image]
Status badge:      [RUNNING] [STOPPED] [DEGRADED] [ERROR]

Data display primitives:

Metric row:        p95: 92ms   req/min: 340   err: 0.12%
Key/value row:     workspace: apps/system-dashboard
Table row:         | app-id | status | p95 | actions |
Bar meter:         CPU [##########......] 62%
Sparkline:         trend ▁▂▃▄▅▄▃▂
Log line:          10:42:14 WARN backlog threshold=12

Panel composition example:

+-----------------------------------------------------------------------------------+
| Launch Configuration                                                               |
| [ App: system-dashboard____________________ ] [ Environment: dev v ]              |
| [x] Include diagnostics   [ ] Enable write-mode   (o) New window  ( ) New tab    |
| [ Notes:                                                                          |
|   | open detached window with telemetry ribbon                                    |
| ]                                                                                 |
| [Cancel]                                               [Preview] [Launch Window]  |
+-----------------------------------------------------------------------------------+

Component naming guidance:

1. Keep repeated labels stable (workspace, status, health, p95, actions).
2. Use bracketed controls for actions ([Open], [Stop], [Details]).
3. Use [x]/[ ] for checkboxes and (o)/( ) for radio choices.
4. Keep state badges uppercase for deterministic parsing (RUNNING, STOPPED, DEGRADED, ERROR).

Tooling Entry Points

Run all commands from this repo root.

npm run validate:contracts
npm run extract:app -- --app app-manager
npm run compile:app -- --app app-manager
npm run serve:app -- --app app-manager --port 5090

One-Command Workspace Bootstrap (From Sketch)

Use this when a client AI assistant gives you a large sketch markdown file and you need a new workspace quickly.

npm run init:workspace -- --app ops-control-center --sketch ./docs/prototypes/replit-test-app.md --title "Ops Control Center" --port 5092 --compile

What this command generates automatically:

1. apps/<app-id>/ workspace structure.
2. app.manifest.json with compile/serve entrypoints.
3. docs/<app-id>.md copied from the sketch source.
4. sketches/*.sketch.txt extracted from numbered sections.
5. data/*.data.json route payloads generated from sketches.
6. cst/<app-id>.routes.cst.json and cst/<app-id>.route-shell.json.
7. layout/<app-id>.route.layout-tree.json baseline layout.

Installed package usage (for Replit or other environments):

app-lab-init-workspace --app ops-control-center --sketch ./docs/prototypes/replit-test-app.md --title "Ops Control Center" --port 5092 --compile
app-lab-serve --app ops-control-center --port 5092

Replit No-Shortcut Mode

If an external AI assistant tries to hand-author HTML pages, enforce this command gate:

npm run init:workspace -- --app <app-id> --sketch <sketch-md> --title "<display-title>" --port <port> --compile
npm run validate:workspace -- --app <app-id> --strict
npm run validate:contracts
npm run serve:app -- --app <app-id> --port <port>

The validate:workspace command fails when generated HTML is missing, stale relative to source artifacts, or missing route markers. This makes manual HTML shortcuts visible and blocks false completion. When reporting success from hosted environments (for example Replit), require a user-reachable preview URL. http://localhost:<port> by itself is not a valid completion URL unless the user is running locally and confirms localhost access.

Reusable agent contract:

• docs/REPLIT-AGENT-CONTRACT.md

Workspace Runtime API (CST-Driven)

Compiler output exposes generic compiled context, and workspace host runtime scripts may publish an app API:

• window.AppLabSystem
• window.__APP_LAB_SYSTEM_API__
• window.__APP_LAB_COMPILED_CONTEXT__

Workspace-host runtime mode is mandatory. Each app manifest must define entrypoints.appRuntime.bootstrapScript and strict workspace validation enforces it.

Use the workspace-owned API to access CST objects and route data without hard-coded HTML selectors.

Available methods:

• getCst()
• getComponents()
• getRoutes()
• getRoute(routeId)
• getRouteData(routeId?)
• getEmbeddings()
• getEmbedding(key, routeId?)
• queryByEmbedding(key, { routeId? })
• queryOneByEmbedding(key, { routeId? })
• goToRoute(routeId)

Example (script-side):

const api = window.AppLabSystem;
const routeData = api.getRouteData();
const actionButtons = api.queryByEmbedding("primaryActions");
const timelineRows = api.queryByEmbedding("deployTimeline", { routeId: "release-monitor" });

Embeddings are defined in CST and can be scoped:

• cst.embeddings.shared
• cst.embeddings.byRoute[routeId]

This keeps selector knowledge in CST while scripts remain generic and contract-safe. Compiler modules remain app-agnostic and do not own AppLabSystem behavior.

Optional extract:app overrides when needed:

npm run extract:app -- --app app-manager --source ./apps/app-manager/docs/app-manager.md
npm run extract:app -- --app app-manager --indexTitle "App Manager Sketch Index"

See Also

• docs/BOUNDARIES.md
• apps/app-manager/app.manifest.json
• apps/authentication-flow/app.manifest.json