@volter/twin-hubspot 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,197 @@
+# @volter/twin-hubspot
+
+The **HubSpot CRM twin** — a local, stateful, vendor-faithful replica of the
+[HubSpot](https://developers.hubspot.com/docs/api/overview) **CRM v3/v4 API**, on the shared
+[`@volter/world-core`](../../world-core) kernel. An **unmodified `@hubspot/api-client`** — pointed here
+with its own public `basePath` option, or routed by the world injector's `api.hubapi.com`
+interception — talks to it and gets vendor-correct responses.
+
+State lives in the kernel's append-only action/event log — a write appends an action that projects
+into visible state; reads use the kernel’s tree. **No real HubSpot is ever called** (the only network path
+is the connector, over an injected client). The CRM API accepts a **faked-locally Bearer token**; an app's
+**OAuth install** is served (`src/hubspot-oauth.tsx`: the consent at app.hubspot.com/oauth/authorize, the code and
+refresh exchanges at POST /oauth/v1/token, token metadata at GET /oauth/v1/access-tokens/{token}). There is **NO
+signature verification**.
+
+## Usage
+
+```bash
+bun run src/cli.ts serve            # the HubSpot CRM API twin (writable)
+bun run src/cli.ts serve --read-only
+bun run src/cli.ts mirror           # the React CRM mirror (records + the deal pipeline board)
+bun run src/cli.ts conformance      # offline, failable endpoint probe over the live router
+```
+
+Collections use HubSpot's envelope — `{ results, paging: { next: { after } } }` — and errors use
+the documented `{ status: "error", message, correlationId, category }` shape (with `errors[]`
+where the vendor carries per-field detail).
+
+Two deliberate departures from the live vendor, both required by **serve-path determinism**
+(CLAUDE.md — a served response must be a pure function of `(request, stored state)` and
+byte-identical on replay):
+
+- **`correlationId` is DERIVED, not random.** It is a hash of `(method, pathname, status,
+  category, message)` rendered in HubSpot's UUID shape. Real HubSpot mints a fresh one per
+  request; a twin that did the same could not be replayed.
+- **The rate-limit `-Remaining` COUNTERS are not served.** Every response carries HubSpot's
+  documented *policy* headers with the real Professional-tier figures —
+  `X-HubSpot-RateLimit-Max: 190`, `X-HubSpot-RateLimit-Interval-Milliseconds: 10000`,
+  `X-HubSpot-RateLimit-Daily: 625000` — and deliberately **not**
+  `X-HubSpot-RateLimit-Remaining` / `-Daily-Remaining`: a truthful remaining count is a
+  wall-clock-metered, account-wide number no local twin observes, and fabricating one would both
+  break replayability and tell the caller something untrue. Filed as
+  `hubspot.protocol.rate_limit_remaining_headers`.
+
+## Coverage
+
+The capability manifest (`src/hubspot-capabilities.ts`) is the **real HubSpot surface as the
+denominator** — coverage is honest and partial. Run `bun scripts/manifest-baseline-one.ts hubspot`
+for the live count. As of writing: **done=105 / total=231**, regressions=0.
+
+The denominator's source is `@hubspot/api-client` 14.0.1's own generated client — **936 operations
+across eleven top-level API families**, enumerated from every `lib/codegen/**/apis/*Api.js` request
+factory. Those eleven families are censused in `src/hubspot-areas.ts`; the generated request
+factories, response processors and models are also the **oracle** for this twin's paths, status
+codes and response shapes (HubSpot publishes no first-party OpenAPI document this repo can vendor,
+which is why `spec-sources.json` records `kind: "none"` with that as the reason).
+
+### Scope: this is the CRM
+
+`api.hubapi.com` fronts eleven separate HubSpot products. **This twin models the CRM** — records,
+properties, associations, pipelines, owners and the CRM Search API. Two different things follow
+from that, and they get different treatment (the §9 round-one ruling):
+
+- **Surface INSIDE the CRM that is not built yet is a plain `todo`**, however much work it is —
+  engagements, commerce, custom-object schemas, lists, imports/exports and CRM extensions all ride
+  the same `/crm/` routes this twin already serves, so carving them out would be shrinking the
+  denominator rather than describing it (`HUBSPOT_UNMODELED_CRM_CAPABILITIES`).
+- **A separate HubSpot PRODUCT behind the same host is a deferred area**, whose capabilities are
+  `todo` and whose area records why it is a separate product
+  (`HUBSPOT_DEFERRED_AREA_CAPABILITIES`). `hubspot.deferred.area_routes_refused` drives a real request at one route per
+  deferred area — and asserts that route table **bijects with the area census** — proving the twin
+  **refuses** each in HubSpot's own error envelope, never a fabricated success.
+
+Deferred (9 areas, all non-CRM): CMS · Marketing · Automation · Conversations · Files · Events ·
+Communication preferences · Settings · Webhooks.
+
+A CRM object type HubSpot really has but this twin does not model — `notes`, `line_items`, a
+custom object — is refused **honestly** (`404`, "does not model"), never with HubSpot's own
+`Unable to infer object type from` wording, which the vendor uses only for a segment it genuinely
+cannot resolve. All three spellings are covered: the plural name, the `objectTypeId` form
+(`0-46`, `2-3453932`) and the `fullyQualifiedName` form (`p2953265_car`).
+
+**Modeled (proven `done`, each with a failable offline verify):**
+
+- **CRM objects** — contacts / companies / deals / tickets: create, read (with `?properties=` and
+  `?associations=`), list (with the documented 100-per-page cap, `?archived=`, and
+  `paging.next.after` cursor paging), update, archive, and merge. Record ids are minted as
+  `max + 1` over the **id set already in state**, archived rows included, from a **namespaced base**
+  (`HUBSPOT_LOCAL_ID_BASE`, 9e11 — an order of magnitude above the largest HubSpot record id this
+  repo has observed). That covers both collision directions: an archived id is never reused, a
+  local mint never lands on an id a pull observed, and — the direction §9 round one found live — a
+  pull arriving LATER cannot land on a locally minted subject either. `mapCrmObject` additionally
+  stamps `hsLocalMint: false`, so an observed row always wins the addressability question.
+- **Batch** — `batch/create` (201), `batch/read` (200, or **207** with `errors[]` when an id is
+  missing, and `idProperty` lookups), `batch/update`, `batch/upsert` (`new: true|false`),
+  `batch/archive` (204).
+- **CRM Search** — `filterGroups` (AND within a group, OR across groups) over exactly the 13
+  documented `FilterOperatorEnum` values (an operator outside that closed set is a 400), numeric
+  comparison for `LT/LTE/GT/GTE/BETWEEN`, `IN`/`NOT_IN`, presence operators, tokenized
+  `CONTAINS_TOKEN` with a trailing-`*` wildcard, free-text `query`, `sorts`, `properties`
+  projection, offset paging, and the documented 200-per-page / 10 000-result / 5-group /
+  6-filter / 18-filter caps.
+- **Properties + property groups** — the HubSpot-defined property set per object type, plus
+  create / read / update / archive for both, a 409 on a duplicate name, and a custom property that
+  round-trips on a record and is searchable.
+- **Pipelines + stages** — HubSpot's out-of-the-box deal pipeline (`default`, seven stages) and
+  ticket pipeline (`0`, four stages), create / read / update / **replace (PUT, full body
+  required)** / archive, and full stage CRUD. Stage ids come from a persisted monotonic counter,
+  so removing a stage never frees its id for the next one.
+- **Owners** — list, read, `?email=` filter, and owners observed by a connector pull.
+- **Associations (v4)** — the `PUT` with an `AssociationSpec[]` body (201 `LabelsBetweenObjectPair`
+  carrying the NUMERIC objectTypeIds). `AssociationSpec` is a closed **two-key** shape: there is no
+  `label` on the request — HubSpot resolves labels from the association-type *definition*, which
+  this twin does not model, so `labels` is empty and a caller-supplied label is never echoed back.
+  Also the `default` PUT
+  using HubSpot's documented type ids (contact→company 279 / company→contact 280 / …),
+  bidirectional readback, archive from both directions, the `associations` block on a create, the
+  closed `AssociationSpec` category set, and batch create/read/archive.
+- **Protocol** — the documented error envelope, unmodeled ops failing like the vendor (404),
+  read-only rejecting writes (405), the rate-limit policy headers, deterministic replay, and the
+  three kernel-reserved field names (`id`/`createdAt`/`updatedAt`) surviving the projection.
+- **Connector** — pull the four object types plus owners, following `paging.next.after`;
+  idempotent re-pull; a **refused** pull throws rather than folding an empty account over real
+  state (including a failure delivered as HTTP 200 with an error envelope); push confirms only on
+  a genuine success, and **never addresses a locally minted record id at a real portal**.
+- **UI mirror** — the contacts list, the **deal pipeline board** (grouping asserted per column,
+  not just card counts), the stage pills, the record property sheet, the nav (bijected against
+  `MIRROR_SECTIONS`, so deleting a destination reddens it), the empty state, and the **write
+  path** — a UI write goes through the vendor's own endpoint on the same handler, and an
+  A→B→A revert through it still lands. All **data-coupled** (seed through the twin's write
+  path → fetch the SAME vendor endpoint the screen reads → render the mirror's OWN component →
+  assert the seeded value survives), plus two Playwright journeys.
+
+**Todo (real surface, not yet modeled):** the six unbuilt CRM families above (engagements,
+commerce, custom-object schemas, lists, imports/exports, extensions), `?idProperty=` reads,
+`propertiesWithHistory`,
+GDPR delete, per-object required-property and enumeration validation, unique-value conflicts,
+HubSpot's automatic de-duplication, batch size caps and partial-207 creates, search sort direction
+and association filters, calculated properties, pipeline audit trails
+and stage validation on records, association label definitions and cardinality limits, 401/403
+auth refusals, the 429 body, connector pulls of properties/pipelines/associations and push id
+reconciliation, and the board drag-to-stage / saved-views / search-bar / inline-edit UI screens.
+
+Also planned: **Breeze / AI content assistant endpoints** — the documented request/response
+envelope with a deterministic, labeled twin-stub result — plus the deferred product areas above.
+
+### The human surface: this vendor gets a mirror
+
+Settled with the recipe's rule, not by "does a UI exist": **when someone does HubSpot's core job,
+do they open a browser or write code?** A sales rep works a deal by dragging it across the pipeline
+board and a support agent works a ticket in the ticket view — the CRM screen *is* the product, the
+same shape as Jira's board. So this pack ships a mirror, and it is **archetype A (API
+passthrough)**: non-asset requests fall through to `handleHubspotTwinRequest` and the browser
+client fetches HubSpot's real API paths, so API↔UI parity cannot drift — there is only one code
+path.
+
+## Files
+
+- `src/hubspot-twin.ts` — the CRM v3/v4 request handler (routes → kernel writes/reads) and the
+  hand-authored endpoint census.
+- `src/hubspot-server.ts` — `createHubspotTwinServer({ root?, port?, readOnly? })`.
+- `src/hubspot-mirror-ui.ts` + `client/hubspot-mirror.tsx` — the React CRM mirror.
+- `src/hubspot-connector.ts` — pull/push over an injected executor (`liveHubspotExecute` for real I/O).
+- `src/hubspot-conformance.ts` — one live request per claimed endpoint, plus a router census
+  checked in both directions (dev-only; lazy-imported by the CLI).
+- `src/hubspot-areas.ts` / `src/hubspot-deferred-capabilities.ts` — the top-down product-area
+  census and the deferred areas' todos.
+- `src/hubspot-capabilities.ts` — the capability manifest (the real vendor surface).
+- `src/hubspot-sdk.integration.test.ts` — the **unmodified `@hubspot/api-client` 14.0.1** driving
+  the twin over its own public `basePath` option (a devDependency; never in the runtime graph).
+
+## Rate budget — the fail-closed backstop on live calls
+
+`liveHubspotExecute` is the **one place** this pack issues a live request, so every call it makes
+is charged against a persistent, fail-closed spend ledger **before** the request goes out. Past the
+ceiling, or while a `Retry-After`/429 cooldown is armed, it **throws instead of calling**. The
+ledger is keyed by vendor and a hash of the credential (limits are per app/token, so it is
+deliberately *not* cwd-scoped) and persists across processes, so a fresh process does not get a
+fresh allowance; a corrupt ledger counts as a **full** window rather than zero spend. There is no
+option to disable it, and no value you can pass for `budget` that yields an unguarded client — an
+injected budget is validated by *method identity*, so a subclass or a `Proxy` that replaces
+`checkBudget` is refused.
+
+The declared numbers: **30 weighted units / 10 s** — HubSpot's own 10-second interval, at under a
+third of its tightest published tier (Free/Starter: 100 requests per 10 seconds for a privately
+distributed app; Professional and Enterprise get 190, the API-add-on 250, a public OAuth app 110).
+CRM **search** costs 3, anchored in HubSpot's own separate five-requests-per-second search limit;
+**batch object writes** cost 5 and **batch association writes** 3 — judgement calls, because one
+batch call mutates up to 100 real CRM records.
+
+The mechanism is **shared and vendor-agnostic** — it lives in the kernel (`@volter/world-core` →
+`packages/world-core/src/rateBudget.ts`); what lives here in
+[`src/hubspot-budget.ts`](src/hubspot-budget.ts) is this vendor's **declaration** (window, ceiling,
+per-endpoint weights, and a `reason` citing the limits above) plus the vendor-bound
+`HubspotBudget`. The rule is ratified as [../../../docs/contributing/architecture.md](../../../docs/contributing/architecture.md) **D8**, and
+the kernel module's header documents what the guard does *not* guarantee — read that before
+trusting it.

package/client/hubspot-mirror.css

@@ -0,0 +1,43 @@
+:root {
+  --bg: #f5f8fa;
+  --panel: #ffffff;
+  --line: #dfe3eb;
+  --text: #33475b;
+  --muted: #7c98b6;
+  --accent: #eaf0f6;
+  --brand: #ff7a59;
+  --ok: #00bda5;
+  --warn: #f5c26b;
+  --bad: #f2545b;
+}
+* { box-sizing: border-box; }
+body { margin: 0; font-family: -apple-system, system-ui, "Helvetica Neue", sans-serif; background: var(--bg); color: var(--text); }
+.app { display: grid; grid-template-columns: 220px 1fr; grid-template-rows: 56px 1fr; min-height: 100vh; }
+.topbar { grid-column: 1 / 3; display: flex; align-items: center; justify-content: space-between; padding: 0 20px; border-bottom: 1px solid var(--line); background: var(--panel); }
+.brand { font-weight: 700; color: var(--brand); letter-spacing: 0.2px; }
+.view-toggle { border: 1px solid var(--line); background: var(--panel); color: var(--text); border-radius: 4px; padding: 6px 14px; cursor: pointer; font-size: 13px; }
+.view-toggle:hover { background: var(--accent); }
+.sidebar { border-right: 1px solid var(--line); padding: 14px 10px; background: var(--panel); }
+.nav-item { display: block; width: 100%; text-align: left; background: none; border: none; color: var(--muted); padding: 9px 12px; border-radius: 4px; cursor: pointer; font-size: 14px; }
+.nav-item.active, .nav-item:hover { background: var(--accent); color: var(--text); }
+.content { padding: 24px; overflow: auto; }
+table { width: 100%; border-collapse: collapse; background: var(--panel); border: 1px solid var(--line); border-radius: 6px; }
+th { text-align: left; color: var(--muted); font-size: 11px; text-transform: uppercase; letter-spacing: 0.4px; padding: 10px 12px; border-bottom: 1px solid var(--line); }
+td { padding: 12px; border-bottom: 1px solid var(--line); font-size: 14px; }
+tr:last-child td { border-bottom: none; }
+.cell-title { font-weight: 600; }
+.cell-id { color: var(--muted); font-variant-numeric: tabular-nums; }
+.cell-prop-name { color: var(--muted); font-size: 12px; width: 40%; }
+.pill { display: inline-block; padding: 3px 10px; border-radius: 999px; font-size: 12px; background: var(--accent); }
+.pill-ok { background: rgba(0, 189, 165, 0.16); color: var(--ok); }
+.pill-warn { background: rgba(245, 194, 107, 0.22); color: #b07d1a; }
+.pill-bad { background: rgba(242, 84, 91, 0.16); color: var(--bad); }
+.empty { color: var(--muted); padding: 28px; background: var(--panel); border: 1px dashed var(--line); border-radius: 6px; }
+.deal-board { display: flex; gap: 14px; align-items: flex-start; overflow-x: auto; padding-bottom: 8px; }
+.board-column { min-width: 220px; background: var(--panel); border: 1px solid var(--line); border-radius: 6px; padding: 12px; }
+.board-column-head { display: flex; align-items: center; justify-content: space-between; margin-bottom: 10px; }
+.board-count { color: var(--muted); font-size: 12px; }
+.deal-card { border: 1px solid var(--line); border-radius: 4px; padding: 10px; margin-bottom: 8px; }
+.deal-amount { color: var(--muted); font-size: 13px; margin-top: 4px; }
+.record-detail { background: var(--panel); border: 1px solid var(--line); border-radius: 6px; padding: 20px; }
+.detail-title { margin: 0 0 14px; font-size: 20px; }

package/client/hubspot-mirror.tsx

@@ -0,0 +1,132 @@
+// HubSpot mirror — React/TSX CRM client. Renders the twin's contacts, companies, deals and
+// tickets by fetching the twin's OWN CRM REST API on the same origin
+// (`/crm/v3/objects/contacts`, …) — HubSpot's real paths, the same ones the SDK calls.
+// API↔UI parity: the screen shows real twin state, not a hardcoded shell.
+import { createRoot } from 'react-dom/client';
+import { useEffect, useState } from 'react';
+import {
+  MIRROR_SECTIONS, SECTION_COLUMNS, formatAmount, groupByStage, recordTitle, stageTone,
+  type HubspotRow, type MirrorSectionKey, type PillTone,
+} from '../src/hubspot-mirror-ui.ts';
+
+// WHERE THIS MIRROR LIVES. Served at a vendor root the base is '' (fetches are root-relative, as
+// before); served under a path prefix with a <base> tag every read and write resolves inside that
+// prefix instead of escaping it.
+const WIRE_BASE = typeof document === 'undefined' || document.querySelector('base[href]') === null ? '' : new URL('.', document.baseURI).pathname.replace(/\/$/, '');
+
+// Map a tone to a STATIC literal class name (a template-literal class is erased by the
+// minifier, so `pill-${tone}` would vanish from the bundle — assert these instead).
+const PILL_CLASS: Record<PillTone, string> = { ok: 'pill pill-ok', warn: 'pill pill-warn', bad: 'pill pill-bad', '': 'pill' };
+
+/** Unwrap HubSpot's collection envelope (`{ results, paging }`) to its results array. */
+async function fetchRows(path: string): Promise<HubspotRow[]> {
+  const res = await fetch(`${WIRE_BASE}${path}`);
+  const body = (await res.json()) as { results?: unknown };
+  return Array.isArray(body.results) ? (body.results as HubspotRow[]) : [];
+}
+
+/** A CRM record list — one `list-row` landmark per record, carrying its HubSpot record id. */
+export function RecordsTable({ section, rows }: { section: MirrorSectionKey; rows: HubspotRow[] }) {
+  if (rows.length === 0) return <div className="empty">No {section} yet.</div>;
+  const columns = SECTION_COLUMNS[section];
+  return (
+    <table className="records-table">
+      <thead>
+        <tr><th>Name</th>{columns.map((c) => <th key={c.prop}>{c.label}</th>)}<th>Record ID</th></tr>
+      </thead>
+      <tbody>
+        {rows.map((r) => (
+          <tr className="list-row" data-record-id={r.id} key={r.id}>
+            <td className="cell-title">{recordTitle(section, r.properties)}</td>
+            {columns.map((c) => (
+              <td className="cell-prop" key={c.prop}>
+                {c.prop === 'amount' ? formatAmount(r.properties?.amount)
+                  : c.prop === 'dealstage'
+                    ? <span className={PILL_CLASS[stageTone(r.properties?.dealstage)]}>{r.properties?.dealstage ?? '—'}</span>
+                    : (r.properties?.[c.prop] ?? '—')}
+              </td>
+            ))}
+            <td className="cell-id">{r.id}</td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}
+
+/** The deal pipeline board — the screen a sales rep actually works in, one column per stage. */
+export function DealBoard({ rows }: { rows: HubspotRow[] }) {
+  const groups = groupByStage(rows);
+  if (groups.length === 0) return <div className="empty">No deals yet.</div>;
+  return (
+    <div className="deal-board">
+      {groups.map((g) => (
+        <section className="board-column" data-stage={g.stage} key={g.stage}>
+          <header className="board-column-head">
+            <span className={PILL_CLASS[stageTone(g.stage)]}>{g.stage}</span>
+            <span className="board-count">{g.rows.length}</span>
+          </header>
+          {g.rows.map((r) => (
+            <article className="deal-card list-row" data-record-id={r.id} key={r.id}>
+              <div className="cell-title">{recordTitle('deals', r.properties)}</div>
+              <div className="deal-amount">{formatAmount(r.properties?.amount)}</div>
+            </article>
+          ))}
+        </section>
+      ))}
+    </div>
+  );
+}
+
+/** Record detail — the property sheet HubSpot shows on the right of a record. */
+export function RecordDetail({ section, rows }: { section: MirrorSectionKey; rows: HubspotRow[] }) {
+  const r = rows[0];
+  if (!r) return <div className="empty">No record.</div>;
+  const entries = Object.entries(r.properties ?? {});
+  return (
+    <section className="record-detail" data-record-id={r.id}>
+      <h2 className="detail-title">{recordTitle(section, r.properties)}</h2>
+      <table className="property-table">
+        <tbody>
+          {entries.map(([k, v]) => (
+            <tr className="list-row" data-prop={k} key={k}>
+              <td className="cell-prop-name">{k}</td>
+              <td className="cell-prop-value">{v ?? '—'}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </section>
+  );
+}
+
+function App() {
+  const [section, setSection] = useState<MirrorSectionKey>('contacts');
+  const [board, setBoard] = useState(false);
+  const [rows, setRows] = useState<HubspotRow[]>([]);
+  useEffect(() => {
+    const sec = MIRROR_SECTIONS.find((s) => s.key === section)!;
+    fetchRows(sec.path).then(setRows).catch(() => setRows([]));
+  }, [section]);
+  return (
+    <div className="app">
+      <header className="topbar">
+        <span className="brand">HubSpot twin</span>
+        {section === 'deals' ? (
+          <button className="view-toggle" onClick={() => setBoard((b) => !b)}>{board ? 'Table' : 'Board'}</button>
+        ) : null}
+      </header>
+      <nav className="sidebar">
+        {MIRROR_SECTIONS.map((s) => (
+          <button key={s.key} className={`nav-item${s.key === section ? ' active' : ''}`} onClick={() => { setSection(s.key); setBoard(false); }}>{s.label}</button>
+        ))}
+      </nav>
+      <main className="content">
+        {section === 'deals' && board ? <DealBoard rows={rows} /> : <RecordsTable section={section} rows={rows} />}
+      </main>
+    </div>
+  );
+}
+
+const el = typeof document !== 'undefined' ? document.getElementById('root') : null;
+if (el) createRoot(el).render(<App />);