Deep-Learning-Profiling-Tools · latentCall145 · May 18, 2026
diff --git a/.github/workflows/ARCHITECTURE.md b/.github/workflows/ARCHITECTURE.md
@@ -1,7 +1,7 @@
-The `.github/workflows/` directory contains automation for the LL-viz wrapper repository.
+The `.github/workflows/` directory contains automation for the LL-viz app repository.
 
-`ci.yml` validates the `tensor-viz/` submodule from a clean checkout. It installs the Python package, installs Node dependencies, installs Chromium for Playwright, then runs typecheck, tests, and build. This catches both TypeScript/Python unit failures and browser startup failures in the demo app.
+`ci.yml` validates the root LL-viz frontend from a clean checkout. Until the new `@tensor-viz/*` npm packages are published, it checks out the tensor-viz extraction branch into a temporary directory, packs `@tensor-viz/viewer-core` and `@tensor-viz/viewer-demo`, installs those tarballs through npm, installs Chromium for Playwright, then runs typecheck, unit tests, browser e2e tests, and build. This catches linear-layout parser/model failures, package-boundary import failures, and browser startup regressions before release.
 
-`deploy-pages.yml` builds the static viewer demo from the submodule and publishes `tensor-viz/packages/viewer-demo/dist` to GitHub Pages. It does not run the full test suite because deployment should consume a commit that CI has already validated.
+`deploy-pages.yml` builds the root Vite app with the same temporary tensor-viz tarball install path and publishes `dist/` to GitHub Pages. It does not run the full test suite because deployment should consume a commit that CI has already validated.
 
-Workflow changes should preserve the submodule checkout step. Without it, CI can pass repository setup while testing none of the viewer code.
+Workflow changes should keep CI pointed at the root package. Tensor-viz is consumed through npm package artifacts, so bringing back submodule checkout would hide package-boundary failures that this repository is meant to catch. Once `@tensor-viz/viewer-core` and `@tensor-viz/viewer-demo` are published, replace the temporary checkout/pack steps with a plain `npm install`.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -8,23 +8,28 @@ on:
       - linear-layout-website
 
 jobs:
-  tensor-viz:
+  linear-layout-viz:
     runs-on: ubuntu-latest
-    defaults:
-      run:
-        working-directory: tensor-viz
+    env:
+      TENSOR_VIZ_REF: ll-viz-extraction
     steps:
+      - uses: actions/checkout@v4
       - uses: actions/checkout@v4
         with:
-          submodules: true
+          repository: Deep-Learning-Profiling-Tools/tensor-viz
+          ref: ${{ env.TENSOR_VIZ_REF }}
+          path: .tensor-viz-source
       - uses: actions/setup-node@v4
         with:
           node-version: 22
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-      - run: python -m pip install -e .
       - run: npm install
+        working-directory: .tensor-viz-source
+      - run: |
+          mkdir -p ../.tensor-viz-packs
+          npm pack --workspace @tensor-viz/viewer-core --pack-destination ../.tensor-viz-packs
+          npm pack --workspace @tensor-viz/viewer-demo --pack-destination ../.tensor-viz-packs
+        working-directory: .tensor-viz-source
+      - run: npm install --no-save .tensor-viz-packs/tensor-viz-viewer-core-0.1.0.tgz .tensor-viz-packs/tensor-viz-viewer-demo-0.1.0.tgz
       - run: npx playwright install --with-deps chromium
       - run: npm run typecheck
       - run: npm run test

diff --git a/.github/workflows/deploy-pages.yml b/.github/workflows/deploy-pages.yml
@@ -18,11 +18,18 @@ concurrency:
 jobs:
   build:
     runs-on: ubuntu-latest
+    env:
+      TENSOR_VIZ_REF: ll-viz-extraction
     steps:
       - name: Checkout
         uses: actions/checkout@v5
+
+      - name: Checkout tensor-viz package source
+        uses: actions/checkout@v5
         with:
-          submodules: recursive
+          repository: Deep-Learning-Profiling-Tools/tensor-viz
+          ref: ${{ env.TENSOR_VIZ_REF }}
+          path: .tensor-viz-source
 
       - name: Setup Node
         uses: actions/setup-node@v4
@@ -32,18 +39,27 @@ jobs:
       - name: Configure GitHub Pages
         uses: actions/configure-pages@v5
 
-      - name: Install frontend dependencies
+      - name: Install tensor-viz package dependencies
         run: npm install
-        working-directory: tensor-viz
+        working-directory: .tensor-viz-source
+
+      - name: Pack tensor-viz npm packages
+        run: |
+          mkdir -p ../.tensor-viz-packs
+          npm pack --workspace @tensor-viz/viewer-core --pack-destination ../.tensor-viz-packs
+          npm pack --workspace @tensor-viz/viewer-demo --pack-destination ../.tensor-viz-packs
+        working-directory: .tensor-viz-source
+
+      - name: Install frontend dependencies
+        run: npm install --no-save .tensor-viz-packs/tensor-viz-viewer-core-0.1.0.tgz .tensor-viz-packs/tensor-viz-viewer-demo-0.1.0.tgz
 
       - name: Build static viewer demo
-        run: npm run build --workspace @tensor-viz/viewer-demo
-        working-directory: tensor-viz
+        run: npm run build
 
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v4
         with:
-          path: tensor-viz/packages/viewer-demo/dist
+          path: dist
 
   deploy:
     runs-on: ubuntu-latest

diff --git a/.gitignore b/.gitignore
@@ -6,4 +6,6 @@ __pycache__/
 node_modules/
 dist/
 build/
+test-results/
+playwright-report/
 assets/*mp4
diff --git a/.gitmodules b/.gitmodules
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
@@ -1,9 +1,9 @@
-This repository is the LL-viz wrapper around the reusable `tensor-viz` viewer.
+This repository is the LL-viz app built on the reusable `tensor-viz` viewer packages.
 
 The root owns the Triton linear-layout demo inputs and project documentation. `demo_linear_layout.py` defines the sample layouts that users can run locally. `linear_layout_viz.py` converts Triton `LinearLayout` objects into tensor-viz session data, including hardware/logical tensors, colors, markers, and linear-layout metadata.
 
-The `tensor-viz/` submodule owns the viewer implementation. Its TypeScript packages render the UI, its Python package serves local sessions, and its linear-layout extension owns presets, widgets, parsing, and browser behavior. Root code should call into that package instead of duplicating viewer logic here.
+The browser app lives at the root. `src/main.ts` imports `startDemoApp(...)` from `@tensor-viz/viewer-demo` and passes the local linear-layout extension factory. That package boundary is intentional: tensor-viz owns generic viewer rendering and shell behavior, while LL-viz owns GPU layout presets, compose-layout parsing, linear-layout widgets, and fallback tabs.
 
-The root CI checks the submodule because that is where the app builds and tests. When the submodule pointer changes, CI installs Python and Node dependencies inside `tensor-viz/`, installs Chromium for Playwright, runs typecheck, runs tests, and builds packaged frontend assets.
+The TypeScript extension lives in `src/extensions/linear-layout/`. `extension.ts` is the only file the tensor-viz shell sees; model files parse and evaluate layouts, preset files describe instruction families declaratively, and widget files render the sidebar controls.
 
-Keep new root code narrowly focused on LL-viz examples or project-level docs. Runtime behavior, widget behavior, rendering, and preset data should normally be changed inside `tensor-viz/` with architecture notes next to that subsystem.
+The root CI installs npm dependencies, runs typecheck, runs unit tests, runs Playwright against the real app, and builds `dist/` for Pages. Python helpers depend on the published `tensor-viz` Python package rather than a checked-out submodule.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,126 +1,89 @@
 # Contributing
 
-**NOTE: This project was purely built with coding agents, and any contributions will be purely reviewed by coding agents. As for now, only PRs that add/modify layout presets will be considered as the rest of the codebase is subject to change.**
+**NOTE: This project was built with coding agents, and contributions are reviewed
+with coding-agent assistance. For now, preset additions and fixes are the
+expected external contribution path.**
 
 ## Setup
 
-This repository wraps the `tensor-viz/` submodule, where the viewer code lives.
+Install the root frontend dependencies and the published Python viewer package:
 
 ```bash
-git submodule update --init --recursive
-cd tensor-viz
 npm install
 npx playwright install chromium
-git config core.hooksPath .githooks
 python -m venv .venv
 source .venv/bin/activate
-pip install -e .
+pip install tensor-viz
 npm run build
 ```
 
-To check that linear-layout-viz is installed correctly, run this in the project root directory after building tensor-viz above:
+If the matching `@tensor-viz/viewer-core` and `@tensor-viz/viewer-demo` npm
+packages have not been published yet, build local tarballs from the tensor-viz
+extraction branch and install them with `npm install --no-save <tarball paths>`.
+The CI workflow does this automatically until those packages are available from
+the registry.
+
+On Windows PowerShell, activate the environment with:
+
+```powershell
+.venv\Scripts\Activate.ps1
+```
+
+To check the Python demo, run:
 
 ```bash
 python demo_linear_layout.py
 ```
 
 ## Testing Changes
 
-Run the full test suite from `tensor-viz/`:
+Run the full frontend suite before submitting a change:
 
 ```bash
+npm run typecheck
 npm run test
-```
-
-Before submitting any code change, also run:
-
-```bash
 npm run build
 ```
 
-The build is required even if tests pass because it refreshes the built demo
-assets served by the Python package.
-
 Focused checks are useful while iterating:
 
 ```bash
-npm run check:ts-docs
-npm run check:ts-docs:staged
-npm run test --workspace @tensor-viz/viewer-core
-npm run test --workspace @tensor-viz/viewer-demo
-PYTHONPATH=python/src python -m unittest discover -s python/tests -p 'test_*.py'
+npm run test:unit
+npm run test:e2e
+npm run sync:linear-layout-examples
 ```
 
-The TypeScript docs check enforces JSDoc blocks on declarations, a minimum
-comment-line density, and the helper-function rule from `AGENTS.md`: non-exported
-top-level helpers should have at least three local references unless their JSDoc
-marks them as an `@interfaceBoundary`.
-
-`npm run check:ts-docs:staged` is what the pre-commit hook runs; it audits each
-staged TypeScript source file as a whole file. `npm run check:ts-docs` audits the
-full TypeScript tree and may fail while existing files are still being brought up
-to the documentation standard. For targeted cleanup, run
-`node tools/check-ts-docs.mjs packages/viewer-demo/src/app-entry.ts` from
-`tensor-viz/`.
+`npm run sync:linear-layout-examples` rewrites the generated baked-example block
+inside `src/extensions/linear-layout/linear-layout.ts` from
+`demo_linear_layout.py`. Run it after changing the Python demo layouts.
 
 ## File Structure
 
-- `README.md`: project overview, public website links, and top-level setup.
-- `MANUAL.md`: user-facing viewer interaction guide.
-- `linear_layout_viz.py`, `demo_linear_layout.py`: root-level linear layout demos.
-- `assets/`: source media used by the README and project pages.
-- `docs/manual-site/`, `docs/manual-vids/`, `docs/sample-svgs/`: generated or
-  curated documentation assets.
-- `tensor-viz/`: submodule containing the Python package, TypeScript packages,
-  demo app, tests, docs, and build tooling.
-
-Inside `tensor-viz/`:
-
-- `packages/viewer-core/src/`: reusable viewer engine, layout math, session
-  model, rendering, and core tests.
-- `packages/viewer-demo/src/`: the full linear-layout demo app and UI.
-- `packages/viewer-demo/src/extensions/linear-layout/`: LL-viz extension,
-  parser/model code, preset definitions, widgets, and tests.
-- `python/src/tensor_viz/`: Python package and local server.
-- `python/tests/`: Python documentation and API tests.
-- `docs/`: Sphinx and TypeDoc documentation sources.
-- `tools/`: synchronization scripts for examples and built demo assets.
+- `src/main.ts`: root Vite entrypoint that starts the tensor-viz shell with the
+  LL-viz extension factory.
+- `src/extensions/linear-layout/`: parser/model code, preset definitions,
+  sidebar widgets, viewer synchronization, and unit tests.
+- `linear_layout_viz.py`, `demo_linear_layout.py`: Python helpers and examples
+  that produce tensor-viz sessions for Triton `LinearLayout` objects.
+- `e2e/`: Playwright smoke tests for the real browser app.
+- `assets/`, `docs/`, `MANUAL.md`: website media, manual assets, and
+  user-facing docs.
+
+Tensor-viz itself is no longer vendored here. Generic viewer behavior belongs in
+the `Deep-Learning-Profiling-Tools/tensor-viz` repository and should be consumed
+through the published `@tensor-viz/*` npm packages.
 
 ## Architecture Guides
 
-To add/modify features within the current system architecture, architecture docs live next to the code they describe:
-
-- [Linear layout demo app](./tensor-viz/packages/viewer-demo/src/ARCHITECTURE.md):
-  demo shell, extension registry, and app-level lifecycle hooks.
-- [Root LL-viz wrapper](./ARCHITECTURE.md): root demo scripts, submodule
-  boundary, and CI/deploy ownership.
-- [Tensor-viz monorepo](./tensor-viz/ARCHITECTURE.md): package boundaries,
-  build order, and test responsibilities.
-- [Linear layout extension](./tensor-viz/packages/viewer-demo/src/extensions/linear-layout/ARCHITECTURE.md):
-  parsing, composition, runtime metadata, widgets, and generated Python.
-- [Linear layout presets](./tensor-viz/packages/viewer-demo/src/extensions/linear-layout/presets/ARCHITECTURE.md):
-  adding NVIDIA, AMD, or other preset families.
-- [Linear layout widgets](./tensor-viz/packages/viewer-demo/src/extensions/linear-layout/widgets/ARCHITECTURE.md):
-  sidebar UI ownership and shared widget code.
-- [Viewer core](./tensor-viz/packages/viewer-core/src/ARCHITECTURE.md):
-  reusable layout, view, session, and rendering behavior.
-- [Python package](./tensor-viz/python/src/tensor_viz/ARCHITECTURE.md):
-  Python API, session normalization, and local serving.
-- [Root documentation assets](./docs/ARCHITECTURE.md) and
-  [tensor-viz package docs](./tensor-viz/docs/ARCHITECTURE.md): manual pages,
-  Sphinx docs, generated references, and demo asset synchronization.
-- [Browser e2e tests](./tensor-viz/packages/viewer-demo/e2e/ARCHITECTURE.md):
-  Playwright smoke coverage for startup, widgets, command palette, and canvas
-  paint.
-
-## Documentation Standards
-
-For a given design change (e.g. adding/modifying a subsystem), update the relevant
-`ARCHITECTURE.md` file(s) explaining the purpose of the subsystem, folder file
-structure, what each file does, and instructions for workflows using your subsystem.
-Keep user-facing behavior in `MANUAL.md` or `tensor-viz/docs/`, and keep this file
-limited to setup, checks, review expectations, and pointers.
-
-When a change makes existing documentation misleading, update the docs in the
-same change. Prefer one source of truth with links over copying the same
-procedure into several files.
+Architecture docs live next to the code they describe:
+
+- [Root LL-viz app](./ARCHITECTURE.md)
+- [Linear layout extension](./src/extensions/linear-layout/ARCHITECTURE.md)
+- [Linear layout presets](./src/extensions/linear-layout/presets/ARCHITECTURE.md)
+- [Linear layout widgets](./src/extensions/linear-layout/widgets/ARCHITECTURE.md)
+- [Root documentation assets](./docs/ARCHITECTURE.md)
+- [Browser e2e tests](./e2e/ARCHITECTURE.md)
+
+When a change modifies a subsystem, update the relevant `ARCHITECTURE.md` in the
+same change. Keep user-facing behavior in `MANUAL.md`; keep this file focused on
+setup, checks, and review expectations.
diff --git a/README.md b/README.md
@@ -13,36 +13,37 @@ See [docs/sample-svgs/](./docs/sample-svgs/README.md) for example exported SVGs.
 
 ## Structure
 
-- `tensor-viz/`: git submodule pointing at `Deep-Learning-Profiling-Tools/tensor-viz`
+- `src/extensions/linear-layout/`: LL-viz extension, parser/model code, presets,
+  widgets, and tests.
+- `linear_layout_viz.py`, `demo_linear_layout.py`: Python helpers that generate
+  tensor-viz session data for Triton `LinearLayout` objects.
+- `assets/`, `docs/`, `MANUAL.md`: website media and user-facing guides.
 
 ## Setup
 
 ```bash
-git submodule update --init --recursive
-cd tensor-viz
 npm install
 python -m venv .venv
 source .venv/bin/activate
-pip install -e .
+pip install tensor-viz
 npm run build
 ```
 
 ### One-time GitHub setup
 
-1. Push this repo, including the submodule pointer you want Pages to build.
+1. Push this repo.
 2. In GitHub, open `Settings -> Pages`.
 3. Under `Build and deployment`, set `Source` to `GitHub Actions`.
 4. Push to `main`, or run the `Deploy GitHub Pages` workflow manually from the Actions tab.
 
 ### Local preview of the same static site
 
 ```bash
-cd tensor-viz
 npm install
-npm run build --workspace @tensor-viz/viewer-demo
+npm run build
 ```
 
-The built site is written to `tensor-viz/packages/viewer-demo/dist`.
+The built site is written to `dist/`.
 
 ## Usage
 

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
@@ -4,4 +4,6 @@ The root `docs/` directory holds project-level documentation assets for the host
 
 The root `MANUAL.md` is the source of truth for user-facing viewer behavior in this repository. When behavior changes, update `MANUAL.md` first, then refresh or curate the assets that illustrate that behavior. Do not hand-edit generated manual output when the source document or sync script should own the change.
 
-For package-level API documentation, use `tensor-viz/docs/ARCHITECTURE.md` instead. For demo assets copied into the package build, use the sync scripts under `tensor-viz/tools/` and finish with `npm run build` from `tensor-viz/`.
+For package-level tensor-viz API documentation, use the upstream `tensor-viz`
+repository. For LL-viz demo assets, keep source media in this docs tree and
+finish with `npm run build` from the repository root.
diff --git a/docs/manual-site/ARCHITECTURE.md b/docs/manual-site/ARCHITECTURE.md
@@ -2,4 +2,6 @@ The `docs/manual-site/` directory contains the static manual page served by proj
 
 Treat this directory as generated or curated output, not as the primary design record. The root `MANUAL.md` should explain user-facing behavior first. Regenerate or refresh this site output only after the source manual text is correct.
 
-Do not add runtime code here. The viewer implementation lives in `tensor-viz/`, and the project-level manual exists only to document how to use it.
+Do not add runtime code here. Generic viewer implementation lives in the
+upstream tensor-viz packages, LL-viz runtime code lives under `src/`, and the
+project-level manual exists only to document how to use the app.
diff --git a/e2e/ARCHITECTURE.md b/e2e/ARCHITECTURE.md
@@ -0,0 +1,12 @@
+The `e2e/` directory contains browser-level checks for the packaged LL-viz app.
+
+`viewer-smoke.spec.ts` starts the root Vite app through Playwright, verifies that
+the tensor-viz shell boots, confirms the linear-layout extension widgets are
+visible, checks that the viewport paints nonblank tensor content, and opens the
+command palette. This catches the failures unit tests miss: missing package
+exports, broken extension registration, CSS/asset mistakes, and renderer startup
+problems.
+
+Keep e2e tests small. Parser, preset, and mapping behavior should be covered in
+`src/extensions/linear-layout/linear-layout.test.ts`; Playwright should only
+protect workflows that require a real browser.