@flashdsm/genome 0.2.0 → 0.3.0

package/README.md

@@ -34,6 +34,8 @@ npx @flashdsm/genome@latest connect
 
 `connect` scans the folder (stylesheets, CSS inside JS/TS, Tailwind config, theme modules, tokens files; nothing else is read) and opens Flash in your browser, showing what it found and a short code that matches the one in your terminal. Click **Connect** there: Flash creates the system in your account, and the command links the repo (`genome.config.json`), writes the system into it (`pull --confirm`) and stores a token bound to that system under `~/.config/flash-dsm/`. Inside Claude Code it also adds Genome as the project's MCP server; elsewhere it prints the line to add. `--name` overrides the name, which otherwise comes from `package.json`; `--no-open` prints the link instead of opening it.
 
+When your app's dev server is running, `connect` also leaves a live preview in the background (localhost:4747): Flash's editor shows your real app and recolours it as you edit tokens, through its CSS variables. Nothing is written to your code. `npx @flashdsm/genome@latest preview` starts it again; `preview --stop` ends it.
+
 The link works once and expires after 15 minutes. `init --code` does the same with a setup code instead of the browser.
 
 ## Quick start
@@ -112,13 +114,27 @@ diff behind.
 | Tool           | What it does                                                                                          |
 | -------------- | ----------------------------------------------------------------------------------------------------- |
 | `detect_drift` | Read-only. Whether the repo's pulled files moved, whether Flash moved, and which token values changed |
-| `push_to_web`  | Proposes the changed token values to Flash as one change set, reviewed on the Sync page               |
+| `push_to_web`  | Proposes what the code changed to Flash as one change set, reviewed on the Sync page                  |
+
+`push_to_web` reads the code two ways and sends both in one change set:
+
+- **The app's own stylesheets.** A file layered on Flash's `tokens.css`
+  counts: a light block, `--danger: var(--danger-400)`, new `--text-*`
+  sizes. The files the pull wrote (listed in `genome/genome.lock`) are
+  never read as code.
+- **The pulled `design-tokens.json`.** Value edits, aliases re-pointed
+  (`{color.danger-400}`), tokens added, and a light or dark value for a
+  colour Flash holds in the other theme only.
+
+Flash merges them with one set of rules. A `var(--step)` re-points the
+alias. A colour equal to a ramp step points at that step; a colour no step
+holds gets a step of its own (`neutral-150`) in both themes, so nothing in
+Semantic becomes a bare hex. New names are added, a value Flash has no
+theme for is added and said so, and nothing is deleted. The plan says why
+for every row that is more than a new value.
 
-`push_to_web` reads the `design-tokens.json` the pull wrote, compares it
-with the design system as it is now, and proposes value changes to tokens
-Flash already has. Nothing is applied until someone with edit rights says
-yes. A token added, deleted or re-aliased in the file is flagged rather than
-sent: create, remove and re-point tokens in Flash, then pull.
+Nothing is applied until someone with edit rights says yes. A token deleted
+from the file is flagged, never sent as a delete.
 
 It is a dry run without `confirm: true`, and it refuses to push while Flash
 is ahead of `genome/genome.lock`, because a value left over from the last
@@ -221,7 +237,7 @@ Scripts and CI need no MCP client. These run the same code as the MCP tools
 ```bash
 flash-genome pull                 # print what would be written; writes nothing
 flash-genome pull --confirm       # write the token files, the mirror and genome.lock
-flash-genome push                 # print the token edits that would be proposed
+flash-genome push                 # print what the code changed, as Flash would propose it
 flash-genome push --confirm       # open the change set for review in Flash
 flash-genome drift                # has the repo moved, has Flash, which tokens
 flash-genome drift --json         # the same, as one JSON object (for watchers)

package/dist/{chunk-PHEWKKKF.js → chunk-YA26VZWF.js}

@@ -498,6 +498,7 @@ export {
   parseFlashAtomicDocument,
   GENOME_CONFIG_FILENAME,
   LEGACY_CONFIG_FILENAME,
+  GenomeOutputsSchema,
   GenomeConfigSchema,
   normalizeTokenDocument,
   configCandidates,

package/dist/index.d.ts

@@ -2,7 +2,15 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { WorkspaceScanResult } from '@flash-ds/core';
 
-declare function scanWorkspace(workspaceRoot: string): Promise<WorkspaceScanResult>;
+/**
+ * `skip` leaves files out by their path from the root. A push passes the
+ * files its lock lists: the core rulebook finds them through
+ * `genome.config.json`, which a repo linked with `--config elsewhere` does
+ * not keep at the root.
+ */
+declare function scanWorkspace(workspaceRoot: string, opts?: {
+    skip?: (rel: string) => boolean;
+}): Promise<WorkspaceScanResult>;
 
 type ApiClient = {
     health(): Promise<{
@@ -75,6 +83,14 @@ declare function parseCliArgs(argv: string[]): {
     name?: string;
     /** connect: print the link instead of opening the browser. */
     noOpen: boolean;
+    /** preview: run the proxy in this process (what the background child runs). */
+    serve: boolean;
+    /** preview: stop the background proxy. */
+    stop: boolean;
+    /** preview --serve: the app's dev server, the system, Flash's origin. */
+    devUrl?: string;
+    system?: number;
+    origin?: string;
     /** pull / push: write, rather than print the plan. */
     confirm: boolean;
     /** pull / push / drift: one JSON object on stdout. */