From c7129f9206244c2ba9da6d09891c9f626a15199e Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 29 Jun 2026 11:29:33 +0000 Subject: [PATCH 01/10] docs: restructure README per README guidelines Apply the project README guidelines to @edison/shared, adapting the CLI-oriented patterns to a source-consumed library: - Lead with a dense "what is this" paragraph and a one-line tagline - Add an inline nav bar and a NOTE maturity callout (0.1.0, unpublished) - Add a committed architecture diagram (docs/architecture.svg) plus an ASCII module/build layout in a collapsible Architecture section - Use progressive disclosure with TLDR lines for Quick start, Visual regression tests, and Architecture - Tabulate package entrypoints and link modules out to src/ - Show the EnvConfig schema as an annotated example - Add Credits and a contrib.rocks contributors footer Avoids em dashes and contrastive parallelism so the AI-writing CI check passes. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01BSXhDvj3zDtbbqz8XzL7ke --- README.md | 178 +++++++++++++++++++++++++++++++++--------- docs/architecture.svg | 101 ++++++++++++++++++++++++ 2 files changed, 243 insertions(+), 36 deletions(-) create mode 100644 docs/architecture.svg diff --git a/README.md b/README.md index 6f9a8d0..89c48e9 100644 --- a/README.md +++ b/README.md @@ -5,78 +5,184 @@ [![License: AGPL-3.0-only](https://img.shields.io/badge/license-AGPL--3.0--only-blue.svg)](LICENSE) [![Node.js >= 22](https://img.shields.io/badge/node-%3E%3D22-339933?logo=node.js&logoColor=white)](package.json) -Shared React components, design tokens, and client-side utilities used by Edison Watch. +**Shared React components, design tokens, and client-side utilities for Edison Watch.** -This repository is public so that the shared client code used across Edison Watch can be audited and evaluated. It is intentionally an Edison Watch package, not a generic component library or a hosted service SDK. +What is this • +Quick start • +Entrypoints • +Modules • +Configuration • +Architecture • +Contributing • +License -## Contents +## What is this -- React UI components and Edison design tokens -- Product and security animations used in the Edison Watch clients -- Agent registry data and SVG assets -- Browser-side authentication, configuration, and crypto utilities +`@edison/shared` is a TypeScript package of React UI components, design tokens, and browser-side utilities for the Edison Watch web and desktop clients. It bundles the shared design system (UI primitives, theme tokens, animations, and SVG assets) together with client-side auth, configuration, crypto, and agent-registry helpers, built with [tsdown](https://tsdown.dev) into ESM, CommonJS, and TypeScript declarations. The repository is public so the shared client code can be audited; it is intentionally an Edison Watch package rather than a generic component library or a hosted service SDK. -## Development +

+ Architecture: Edison Watch apps consume @edison/shared, which groups UI and client-service entrypoints over a React and Supabase peer-dependency foundation, built by tsdown to dist/. +

-Requirements: Node.js 22 or later and npm. +> [!NOTE] +> `@edison/shared` is at `0.1.0` and is not published to npm. Edison Watch repositories consume it from source, including through Git submodules. Module subpaths and build output are kept stable so publishing can change without redesigning the public surface. Only values safe to expose in browser bundles belong here: no server credentials, private keys, or privileged tokens. + +## Quick start + +TLDR: `npm ci && npm run build` + +Requires Node.js 22 or later (CI also runs on Node 24) and npm. ```bash -npm ci +npm ci # install dependencies npm run typecheck npm run test -npm run build +npm run build # emits ESM, CJS, and .d.ts to dist/ ``` -The build writes ESM, CommonJS, and TypeScript declaration files to `dist/`. - -Additional commands: +
+More commands ```bash -npm run test:coverage -npm run storybook +npm run lint # eslint +npm run format:check # prettier (use `npm run format` to write) +npm run knip # unused exports / dependencies +npm run test:coverage # vitest with v8 coverage +npm run storybook # component explorer on :6006 npm run build-storybook ``` -## Package Status +
-`@edison/shared` is not currently published to npm. Edison Watch repositories consume it from source, including through Git submodules. The package manifest and build output are maintained so that this can change without redesigning the public module surface. +Consumers of the UI and auth modules must provide the declared peer dependencies: React, React DOM, React Router, and Supabase JS. -Supported package entrypoints include: +## Package entrypoints + +Import only the subpath you need; each is independently tree-shakeable. + +| Entrypoint | Contents | +|------------|----------| +| `@edison/shared` | Root barrel re-exporting the public surface | +| `@edison/shared/ui` and `@edison/shared/ui/*` | React UI components | +| `@edison/shared/hooks/*` | React hooks | +| `@edison/shared/theme/tokens.css` | Edison design tokens (CSS custom properties) | +| `@edison/shared/animations` | Product and security SVG animations | +| `@edison/shared/svg` | SVG asset path/string exports | +| `@edison/shared/auth` | Browser auth and Supabase client | +| `@edison/shared/config` | Client/runtime environment configuration | +| `@edison/shared/crypto` | Client-side crypto utilities | +| `@edison/shared/agent-registry` | Canonical agent icon and metadata registry | + +## Modules + +- **UI components** ([`src/ui/`](src/ui)): Badge, Button, Card, Dialog, Dropdown, EmptyState, ErrorBoundary, Input, Select, Skeleton, SlideOver, SSEIndicator, Switch, Table, Tabs, Toast, and Tooltip. Each ships a matching `*.stories.tsx`. +- **Design tokens** ([`src/theme/tokens.css`](src/theme/tokens.css)): theme color, spacing, and typography custom properties shared across clients. +- **Hooks** ([`src/hooks/`](src/hooks)): small React utilities such as `useAnimatedHeight`. +- **Animations** ([`src/animations/`](src/animations)): self-contained SVG + CSS-keyframe animations for product and threat explainers. See [`src/animations/CLAUDE.md`](src/animations/CLAUDE.md) for the design language and copywriting conventions. +- **SVG assets** ([`src/svg/`](src/svg)): logo, app-icon, and connector SVG path data. +- **Auth** ([`src/auth/`](src/auth)): browser-side authentication and the shared Supabase client. +- **Config** ([`src/config/`](src/config)): runtime environment configuration with demo/release/local switching. +- **Crypto** ([`src/crypto/`](src/crypto)): client-side encryption and secret-key API helpers. +- **Agent registry** ([`src/agent-registry/`](src/agent-registry)): display names, brand colors, and icon data for supported coding agents. + +## Configuration scope + +The client configuration in [`src/config/env-config.ts`](src/config/env-config.ts) intentionally contains Edison Watch service endpoints and browser-facing values. This keeps client behavior auditable and supports the apps that consume the package. Both `demo` and `release` configs are baked into the bundle at build time, and a `local` config resolves against the page origin for the fully-offline stack. + +```ts +export interface EnvConfig { + SUPABASE_URL: string // GoTrue / Supabase auth origin (supabase-js base URL) + SUPABASE_ANON_KEY: string // Publishable anon key (safe in client bundles) + FUNCTIONS_URL: string // Base URL for Supabase edge functions + SENTRY_DSN: string // Error reporting DSN + POSTHOG_API_KEY: string // Product analytics key + POSTHOG_FEEDBACK_SURVEY_ID: string + DEPLOY_ENV: string // "demo" | "release" | "local" + API_BASE_URL: string // Default API server base URL + MCP_BASE_URL: string // Default MCP server base URL + RELEASES_BASE_URL: string // Desktop release bucket (electron-updater feed) +} +``` -- `@edison/shared` -- `@edison/shared/auth`, `@edison/shared/config`, and `@edison/shared/crypto` -- `@edison/shared/ui` and `@edison/shared/ui/*` -- `@edison/shared/hooks/*` -- `@edison/shared/agent-registry`, `@edison/shared/animations`, and `@edison/shared/svg` -- `@edison/shared/theme/tokens.css` +Only values that are safe to expose in browser applications belong in this repository. Do not add server credentials, private keys, privileged API tokens, or other secrets. -Consumers of the UI and auth modules must provide the declared peer dependencies: React, React DOM, React Router, and Supabase JS. +## Architecture -## Configuration Scope +The SVG above is the at-a-glance view. The text diagram below renders everywhere and shows how a consuming app resolves an import down to built output. -The client configuration in `src/config/env-config.ts` intentionally contains Edison Watch service endpoints and browser-facing configuration values. This makes the client behavior auditable and supports the Edison Watch applications that consume this package. +
+Module and build layout -Only values that are safe to expose in browser applications belong in this repository. Do not add server credentials, private keys, privileged API tokens, or other secrets. +``` +Edison Watch app (web / desktop / Electron) + │ import { Button } from '@edison/shared/ui' + ▼ + ┌──────────────────────── @edison/shared ────────────────────────┐ + │ │ + │ Design system Client services │ + │ ├─ ui/ (components) ├─ auth/ (Supabase) │ + │ ├─ hooks/ (React) ├─ config/ (env switching) │ + │ ├─ animations/ (SVG+CSS) ├─ crypto/ (client crypto) │ + │ ├─ svg/ (asset paths) └─ agent-registry/ (icon data) │ + │ └─ theme/tokens.css │ + │ │ + └────────────────────────────┬────────────────────────────────────┘ + │ tsdown build + ▼ + dist/ (ESM .mjs + CJS .cjs + .d.ts) + │ + ▼ + Peer deps provided by consumer: + React · React DOM · React Router · Supabase JS +``` -## Visual Regression Tests +
-Visual tests are currently run manually when UI changes warrant them: +## Visual regression tests -```bash -npm run build-storybook -npm run test:visual -``` +TLDR: `npm run build-storybook && npm run test:visual` + +
+Updating baselines -After intentional visual changes, update and commit the baselines with: +Visual tests run manually when UI changes warrant them. After intentional visual changes, update and commit the baselines: ```bash npm run test:visual:update ``` +Baselines live in [`visual-tests/`](visual-tests). The build is verified in CI (typecheck, lint, format, knip, coverage, build, and Storybook build) on Node 22 and Node 24. + +
+ ## Contributing Issues and focused contributions are welcome. Please open an issue with a clear description, expected behavior, and a minimal reproduction where possible. Broader organization-level contribution and security policies will be published separately. +Two repository conventions worth noting before you open a PR: + +- **Plain prose only.** CI runs [`scripts/check-ai-writing.ts`](scripts/check-ai-writing.ts), which rejects em dashes (U+2014) and contrastive parallelism. Use hyphens and direct phrasing. +- **Folder and file size limits** are enforced by [`scripts/check_folder_sizes.sh`](scripts/check_folder_sizes.sh) and [`scripts/check_large_files.sh`](scripts/check_large_files.sh). + +## Credits + +This package is built with: + +- [React](https://react.dev) and [React Router](https://reactrouter.com) +- [tsdown](https://tsdown.dev) for bundling to ESM/CJS/types +- [Storybook](https://storybook.js.org) for component development +- [Vitest](https://vitest.dev) and [Playwright](https://playwright.dev) for unit and visual tests +- [Supabase JS](https://supabase.com/docs/reference/javascript) for auth +- [simple-icons](https://simpleicons.org) for agent icon paths + +## About the contributors + + + Contributors + + +Made with [contrib.rocks](https://contrib.rocks). + ## License This project is licensed under the [GNU Affero General Public License v3.0 only](LICENSE). diff --git a/docs/architecture.svg b/docs/architecture.svg new file mode 100644 index 0000000..0ad2e8a --- /dev/null +++ b/docs/architecture.svg @@ -0,0 +1,101 @@ + + + + + + + + + + + + + @edison/shared + Shared React components, design tokens & client utilities for Edison Watch apps + + + + CONSUMERS + Edison Watch apps · import from source (incl. Git submodules) + + + + + + + @edison/shared · PACKAGE ENTRYPOINTS + + + + + + UI layer + presentation + + + + @edison/shared/ui · /ui/* + Button · Badge · Card · Dialog · Dropdown · EmptyState + ErrorBoundary · Input · Select · Skeleton · SlideOver · Switch + SSEIndicator · Table · Tabs · Toast · Tooltip + + + + /hooks/* + useAnimatedHeight + + + /animations + product · security + + + /svg + asset strings + + + /theme/tokens.css + design tokens: colors, spacing, typography + + + + + + Client services + logic + + + /auth + browser auth + Supabase client + + + /config + client / env configuration + + + /crypto + client-side crypto utilities + + + /agent-registry + agent registry data + + + + + + + PEER DEPENDENCIES (provided by consumers) + React · React DOM · React Router · Supabase JS + + + tsdown → dist/ (ESM · CJS · .d.ts) + Build: tsdown emits ESM + CJS bundles and TypeScript declarations to dist/. + From 28655cdeb1954d62d810aeb94442ee7ee6df2643 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 29 Jun 2026 11:39:50 +0000 Subject: [PATCH 02/10] docs: use bullet list for README "What is this" Replace the prose paragraph with the prior four-bullet summary. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01BSXhDvj3zDtbbqz8XzL7ke --- README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 89c48e9..1eff503 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,10 @@ ## What is this -`@edison/shared` is a TypeScript package of React UI components, design tokens, and browser-side utilities for the Edison Watch web and desktop clients. It bundles the shared design system (UI primitives, theme tokens, animations, and SVG assets) together with client-side auth, configuration, crypto, and agent-registry helpers, built with [tsdown](https://tsdown.dev) into ESM, CommonJS, and TypeScript declarations. The repository is public so the shared client code can be audited; it is intentionally an Edison Watch package rather than a generic component library or a hosted service SDK. +- React UI components and Edison design tokens +- Product and security animations used in the Edison Watch clients +- Agent registry data and SVG assets +- Browser-side authentication, configuration, and crypto utilities

Architecture: Edison Watch apps consume @edison/shared, which groups UI and client-service entrypoints over a React and Supabase peer-dependency foundation, built by tsdown to dist/. From 9f1558a318e57495c05f838a6fdb44ff7eaf4a92 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 29 Jun 2026 11:40:21 +0000 Subject: [PATCH 03/10] docs: restore auditability and positioning note in README Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01BSXhDvj3zDtbbqz8XzL7ke --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 1eff503..0a5f50a 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,8 @@ - Agent registry data and SVG assets - Browser-side authentication, configuration, and crypto utilities +This repository is public so that the shared client code used across Edison Watch can be audited and evaluated. It is intentionally an Edison Watch package, not a generic component library or a hosted service SDK. +

Architecture: Edison Watch apps consume @edison/shared, which groups UI and client-service entrypoints over a React and Supabase peer-dependency foundation, built by tsdown to dist/.

From 5a06e672c6673953ba81cbe0ef496adbcf4e2d69 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 29 Jun 2026 11:46:32 +0000 Subject: [PATCH 04/10] docs: make architecture diagrams abstract and refactor-resistant Redraw the SVG and ASCII diagrams around durable concepts (two capability domains, standard-module distribution, host runtime) instead of folder names, subpaths, component lists, and specific build tooling, so the diagrams survive routine renames and refactoring. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01BSXhDvj3zDtbbqz8XzL7ke --- README.md | 41 ++++++------- docs/architecture.svg | 130 ++++++++++++++++++------------------------ 2 files changed, 76 insertions(+), 95 deletions(-) diff --git a/README.md b/README.md index 0a5f50a..887c1bc 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ This repository is public so that the shared client code used across Edison Watch can be audited and evaluated. It is intentionally an Edison Watch package, not a generic component library or a hosted service SDK.

- Architecture: Edison Watch apps consume @edison/shared, which groups UI and client-service entrypoints over a React and Supabase peer-dependency foundation, built by tsdown to dist/. + Architecture: Edison Watch applications share @edison/shared, which provides a design-system domain and a client-services domain, shipped as standard JS modules and running on the host application's React runtime and backend platform.

> [!NOTE] @@ -113,32 +113,29 @@ Only values that are safe to expose in browser applications belong in this repos ## Architecture -The SVG above is the at-a-glance view. The text diagram below renders everywhere and shows how a consuming app resolves an import down to built output. +The SVG above is the at-a-glance view. The text diagram below renders everywhere and captures the same durable shape: two capability domains shared by every client, sitting on a host-provided runtime.
-Module and build layout +Conceptual layout ``` -Edison Watch app (web / desktop / Electron) - │ import { Button } from '@edison/shared/ui' - ▼ - ┌──────────────────────── @edison/shared ────────────────────────┐ - │ │ - │ Design system Client services │ - │ ├─ ui/ (components) ├─ auth/ (Supabase) │ - │ ├─ hooks/ (React) ├─ config/ (env switching) │ - │ ├─ animations/ (SVG+CSS) ├─ crypto/ (client crypto) │ - │ ├─ svg/ (asset paths) └─ agent-registry/ (icon data) │ - │ └─ theme/tokens.css │ - │ │ - └────────────────────────────┬────────────────────────────────────┘ - │ tsdown build + Edison Watch applications (web / desktop clients) + │ share one source of truth + ▼ + ┌──────────────────── @edison/shared ────────────────────┐ + │ │ + │ Design system Client services │ + │ (look and feel) (behavior) │ + │ ├─ Reusable UI components ├─ Authentication │ + │ ├─ Design tokens & theming ├─ Runtime configuration │ + │ └─ Motion & illustration ├─ Client-side crypto │ + │ └─ Canonical reference │ + │ │ + └────────────────────────────┬────────────────────────────┘ + │ shipped as standard JS modules ▼ - dist/ (ESM .mjs + CJS .cjs + .d.ts) - │ - ▼ - Peer deps provided by consumer: - React · React DOM · React Router · Supabase JS + Host runtime (provided by the consuming app): + React UI runtime · application data & auth platform ```
diff --git a/docs/architecture.svg b/docs/architecture.svg index 0ad2e8a..b280b7a 100644 --- a/docs/architecture.svg +++ b/docs/architecture.svg @@ -1,11 +1,11 @@ - + @@ -15,87 +15,71 @@ - + @edison/shared - Shared React components, design tokens & client utilities for Edison Watch apps + One shared client foundation for the Edison Watch applications - CONSUMERS - Edison Watch apps · import from source (incl. Git submodules) + CONSUMING APPLICATIONS + Edison Watch web and desktop clients, sharing one source of truth - - @edison/shared · PACKAGE ENTRYPOINTS - - - - - - UI layer - presentation - - - - @edison/shared/ui · /ui/* - Button · Badge · Card · Dialog · Dropdown · EmptyState - ErrorBoundary · Input · Select · Skeleton · SlideOver · Switch - SSEIndicator · Table · Tabs · Toast · Tooltip - - - - /hooks/* - useAnimatedHeight - - - /animations - product · security - - - /svg - asset strings - - - /theme/tokens.css - design tokens: colors, spacing, typography + + @edison/shared + + + + + + Design system + look and feel + + + Reusable UI components + Accessible, themeable interface building blocks + + + Design tokens and theming + The shared visual language across clients + + + Motion and illustration + Product and security explainer graphics - - - - Client services - logic - - - /auth - browser auth + Supabase client - - - /config - client / env configuration - - - /crypto - client-side crypto utilities - - - /agent-registry - agent registry data - - - - - - - PEER DEPENDENCIES (provided by consumers) - React · React DOM · React Router · Supabase JS - - - tsdown → dist/ (ESM · CJS · .d.ts) - Build: tsdown emits ESM + CJS bundles and TypeScript declarations to dist/. + + + + Client services + behavior + + + Authentication and identity + + + Runtime configuration + + + Client-side cryptography + + + Canonical reference data + + + + + + + HOST RUNTIME (provided by the consuming application) + React UI runtime · application data and auth platform + shipped as standard JS modules + + + Built once from a single source and consumed by every Edison Watch client. From 2871b730b6f62e36ea4a05ada500310ced3a4c86 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 29 Jun 2026 12:07:38 +0000 Subject: [PATCH 05/10] docs: collapse package entrypoints and modules behind details Move both reference sections behind
with TLDR lines so the top-level README scan stays short. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01BSXhDvj3zDtbbqz8XzL7ke --- README.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 887c1bc..b4bbe87 100644 --- a/README.md +++ b/README.md @@ -63,7 +63,12 @@ Consumers of the UI and auth modules must provide the declared peer dependencies ## Package entrypoints -Import only the subpath you need; each is independently tree-shakeable. +TLDR: import the subpath you need; see [`package.json`](package.json) `exports` for the full list. + +
+Entrypoints + +Each entrypoint is independently tree-shakeable. | Entrypoint | Contents | |------------|----------| @@ -78,8 +83,15 @@ Import only the subpath you need; each is independently tree-shakeable. | `@edison/shared/crypto` | Client-side crypto utilities | | `@edison/shared/agent-registry` | Canonical agent icon and metadata registry | +
+ ## Modules +TLDR: a design-system half and a client-services half; browse [`src/`](src) for the source. + +
+What lives where + - **UI components** ([`src/ui/`](src/ui)): Badge, Button, Card, Dialog, Dropdown, EmptyState, ErrorBoundary, Input, Select, Skeleton, SlideOver, SSEIndicator, Switch, Table, Tabs, Toast, and Tooltip. Each ships a matching `*.stories.tsx`. - **Design tokens** ([`src/theme/tokens.css`](src/theme/tokens.css)): theme color, spacing, and typography custom properties shared across clients. - **Hooks** ([`src/hooks/`](src/hooks)): small React utilities such as `useAnimatedHeight`. @@ -90,6 +102,8 @@ Import only the subpath you need; each is independently tree-shakeable. - **Crypto** ([`src/crypto/`](src/crypto)): client-side encryption and secret-key API helpers. - **Agent registry** ([`src/agent-registry/`](src/agent-registry)): display names, brand colors, and icon data for supported coding agents. +
+ ## Configuration scope The client configuration in [`src/config/env-config.ts`](src/config/env-config.ts) intentionally contains Edison Watch service endpoints and browser-facing values. This keeps client behavior auditable and supports the apps that consume the package. Both `demo` and `release` configs are baked into the bundle at build time, and a `local` config resolves against the page origin for the fully-offline stack. From 1f9cbf817d2d41a0acfa7e67a1cdb031cfa7ca3d Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 29 Jun 2026 12:11:22 +0000 Subject: [PATCH 06/10] docs: format README with prettier Fixes the CI format:check failure (aligned tables, comment spacing). Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01BSXhDvj3zDtbbqz8XzL7ke --- README.md | 42 +++++++++++++++++++++--------------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index b4bbe87..a62ecaf 100644 --- a/README.md +++ b/README.md @@ -70,18 +70,18 @@ TLDR: import the subpath you need; see [`package.json`](package.json) `exports` Each entrypoint is independently tree-shakeable. -| Entrypoint | Contents | -|------------|----------| -| `@edison/shared` | Root barrel re-exporting the public surface | -| `@edison/shared/ui` and `@edison/shared/ui/*` | React UI components | -| `@edison/shared/hooks/*` | React hooks | -| `@edison/shared/theme/tokens.css` | Edison design tokens (CSS custom properties) | -| `@edison/shared/animations` | Product and security SVG animations | -| `@edison/shared/svg` | SVG asset path/string exports | -| `@edison/shared/auth` | Browser auth and Supabase client | -| `@edison/shared/config` | Client/runtime environment configuration | -| `@edison/shared/crypto` | Client-side crypto utilities | -| `@edison/shared/agent-registry` | Canonical agent icon and metadata registry | +| Entrypoint | Contents | +| --------------------------------------------- | -------------------------------------------- | +| `@edison/shared` | Root barrel re-exporting the public surface | +| `@edison/shared/ui` and `@edison/shared/ui/*` | React UI components | +| `@edison/shared/hooks/*` | React hooks | +| `@edison/shared/theme/tokens.css` | Edison design tokens (CSS custom properties) | +| `@edison/shared/animations` | Product and security SVG animations | +| `@edison/shared/svg` | SVG asset path/string exports | +| `@edison/shared/auth` | Browser auth and Supabase client | +| `@edison/shared/config` | Client/runtime environment configuration | +| `@edison/shared/crypto` | Client-side crypto utilities | +| `@edison/shared/agent-registry` | Canonical agent icon and metadata registry |
@@ -110,16 +110,16 @@ The client configuration in [`src/config/env-config.ts`](src/config/env-config.t ```ts export interface EnvConfig { - SUPABASE_URL: string // GoTrue / Supabase auth origin (supabase-js base URL) - SUPABASE_ANON_KEY: string // Publishable anon key (safe in client bundles) - FUNCTIONS_URL: string // Base URL for Supabase edge functions - SENTRY_DSN: string // Error reporting DSN - POSTHOG_API_KEY: string // Product analytics key + SUPABASE_URL: string // GoTrue / Supabase auth origin (supabase-js base URL) + SUPABASE_ANON_KEY: string // Publishable anon key (safe in client bundles) + FUNCTIONS_URL: string // Base URL for Supabase edge functions + SENTRY_DSN: string // Error reporting DSN + POSTHOG_API_KEY: string // Product analytics key POSTHOG_FEEDBACK_SURVEY_ID: string - DEPLOY_ENV: string // "demo" | "release" | "local" - API_BASE_URL: string // Default API server base URL - MCP_BASE_URL: string // Default MCP server base URL - RELEASES_BASE_URL: string // Desktop release bucket (electron-updater feed) + DEPLOY_ENV: string // "demo" | "release" | "local" + API_BASE_URL: string // Default API server base URL + MCP_BASE_URL: string // Default MCP server base URL + RELEASES_BASE_URL: string // Desktop release bucket (electron-updater feed) } ``` From f5c7d541d8ecddd2f0b1846aa8bd791fb2696912 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 29 Jun 2026 12:15:18 +0000 Subject: [PATCH 07/10] docs: restyle architecture diagram in Edison Hackbox brand Redraw docs/architecture.svg per the Edison brand guide: void-black field, electric-cyan wireframe boxes with solid corner tags (40% width, varied placement for rhythm), white Archivo-stack typography, cyan grid markers and arrows. Architecture content is unchanged. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01BSXhDvj3zDtbbqz8XzL7ke --- docs/architecture.svg | 156 ++++++++++++++++++++++-------------------- 1 file changed, 80 insertions(+), 76 deletions(-) diff --git a/docs/architecture.svg b/docs/architecture.svg index b280b7a..1debf37 100644 --- a/docs/architecture.svg +++ b/docs/architecture.svg @@ -1,85 +1,89 @@ - + - - + + - - + + - - @edison/shared - One shared client foundation for the Edison Watch applications - - - - CONSUMING APPLICATIONS - Edison Watch web and desktop clients, sharing one source of truth - - - - - - - @edison/shared - - - - - - Design system - look and feel - - - Reusable UI components - Accessible, themeable interface building blocks - - - Design tokens and theming - The shared visual language across clients - - - Motion and illustration - Product and security explainer graphics + + + + + + + + + - - - - - Client services - behavior - - - Authentication and identity - - - Runtime configuration - - - Client-side cryptography - - - Canonical reference data - - - - - - - HOST RUNTIME (provided by the consuming application) - React UI runtime · application data and auth platform - shipped as standard JS modules - - - Built once from a single source and consumed by every Edison Watch client. + + @edison/shared + One shared client foundation for the Edison Watch applications + + + + + CONSUMING APPLICATIONS + Edison Watch web and desktop clients, sharing one source of truth + + + + + + + + @EDISON/SHARED + + + + + DESIGN SYSTEM + + + Reusable UI components + + Design tokens and theming + + Motion and illustration + + LOOK AND FEEL + + + + + CLIENT SERVICES + BEHAVIOR + + + Authentication and identity + + Runtime configuration + + Client-side cryptography + + Canonical reference data + + + + + + + + + HOST RUNTIME + React UI runtime · application data and auth platform + + + Built once from a single source, consumed by every Edison Watch client. Shipped as standard JS modules. From 5f1b0138f6ba526ac216ea10f91660330a302598 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 29 Jun 2026 12:56:32 +0000 Subject: [PATCH 08/10] docs: drop repo-convention notes from README Contributing Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01BSXhDvj3zDtbbqz8XzL7ke --- README.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/README.md b/README.md index a62ecaf..5d5ce55 100644 --- a/README.md +++ b/README.md @@ -175,11 +175,6 @@ Baselines live in [`visual-tests/`](visual-tests). The build is verified in CI ( Issues and focused contributions are welcome. Please open an issue with a clear description, expected behavior, and a minimal reproduction where possible. Broader organization-level contribution and security policies will be published separately. -Two repository conventions worth noting before you open a PR: - -- **Plain prose only.** CI runs [`scripts/check-ai-writing.ts`](scripts/check-ai-writing.ts), which rejects em dashes (U+2014) and contrastive parallelism. Use hyphens and direct phrasing. -- **Folder and file size limits** are enforced by [`scripts/check_folder_sizes.sh`](scripts/check_folder_sizes.sh) and [`scripts/check_large_files.sh`](scripts/check_large_files.sh). - ## Credits This package is built with: From 06df9e388cf207a3ab78cc02bc671dac728fc5f8 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 29 Jun 2026 13:21:46 +0000 Subject: [PATCH 09/10] docs: drop redundant Architecture section and ASCII diagram The brand SVG near the top already conveys the architecture, so the duplicate text diagram and its section are removed (and dropped from the nav bar). Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01BSXhDvj3zDtbbqz8XzL7ke --- README.md | 30 ------------------------------ 1 file changed, 30 deletions(-) diff --git a/README.md b/README.md index 5d5ce55..21360bf 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,6 @@ Entrypoints • Modules • Configuration • -Architecture • Contributing • License @@ -125,35 +124,6 @@ export interface EnvConfig { Only values that are safe to expose in browser applications belong in this repository. Do not add server credentials, private keys, privileged API tokens, or other secrets. -## Architecture - -The SVG above is the at-a-glance view. The text diagram below renders everywhere and captures the same durable shape: two capability domains shared by every client, sitting on a host-provided runtime. - -
-Conceptual layout - -``` - Edison Watch applications (web / desktop clients) - │ share one source of truth - ▼ - ┌──────────────────── @edison/shared ────────────────────┐ - │ │ - │ Design system Client services │ - │ (look and feel) (behavior) │ - │ ├─ Reusable UI components ├─ Authentication │ - │ ├─ Design tokens & theming ├─ Runtime configuration │ - │ └─ Motion & illustration ├─ Client-side crypto │ - │ └─ Canonical reference │ - │ │ - └────────────────────────────┬────────────────────────────┘ - │ shipped as standard JS modules - ▼ - Host runtime (provided by the consuming app): - React UI runtime · application data & auth platform -``` - -
- ## Visual regression tests TLDR: `npm run build-storybook && npm run test:visual` From dbe7dbc4421fbc7d6916de2131540c1a4d6bf4e2 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 29 Jun 2026 13:27:58 +0000 Subject: [PATCH 10/10] docs: cut host-runtime box from architecture diagram Drop the host-runtime layer (and the inbound arrow), tighten the canvas height, and update the README alt text to match. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01BSXhDvj3zDtbbqz8XzL7ke --- README.md | 2 +- docs/architecture.svg | 23 +++++++---------------- 2 files changed, 8 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 21360bf..31cb03d 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ This repository is public so that the shared client code used across Edison Watch can be audited and evaluated. It is intentionally an Edison Watch package, not a generic component library or a hosted service SDK.

- Architecture: Edison Watch applications share @edison/shared, which provides a design-system domain and a client-services domain, shipped as standard JS modules and running on the host application's React runtime and backend platform. + Architecture: Edison Watch applications share @edison/shared, which provides a design-system domain and a client-services domain, shipped as standard JS modules.

> [!NOTE] diff --git a/docs/architecture.svg b/docs/architecture.svg index 1debf37..9f26014 100644 --- a/docs/architecture.svg +++ b/docs/architecture.svg @@ -1,4 +1,4 @@ - + - + - - - - + + + + @@ -75,15 +75,6 @@ Canonical reference data - - - - - - - HOST RUNTIME - React UI runtime · application data and auth platform - - Built once from a single source, consumed by every Edison Watch client. Shipped as standard JS modules. + Built once from a single source, consumed by every Edison Watch client. Shipped as standard JS modules.