@nashihang777/dsh-solids-world 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# 变更日志
+
+本文件记录 `@nashihang777/dsh-solids-world` 的发布变更。
+
+## 1.0.0
+
+首个版本：把桌面应用 [solids-world](https://github.com/nashihang777/solids-world)
+的 3D 图鉴移植为 DeepSeek Harness 插件。
+
+- 侧栏图标 + `main` 整页面板两个插槽入口，面板随宿主明暗主题与界面语言；
+- 53 个中英双语条目、五个板块，全部 3D 几何由物理公式实时生成；
+- 分步讲解与镜头联动、小测验与进度、逐条笔记与 Markdown 导出、图鉴画廊；
+- 中/英/别名/拼音检索、超胞与成键/标注/剖切/自旋、轨道与动力学参数控制；
+- 本地 CIF 导入（词法、语法、空间群展开、结构提取全部离线）；
+- 客户端为自包含产物（three.js 内联，仅从宿主取 `react`），样式表作用域到
+  `.sw-atlas`，不改动宿主界面；设置与笔记存于页面 `localStorage`。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nashihang777
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,36 @@
+solids-world for DeepSeek Harness
+=================================
+
+This package re-hosts the desktop application "solids-world" inside the DeepSeek
+Harness Web page.
+
+Upstream work
+-------------
+
+solids-world — 开源可交互的固体物理与原子物理 3D 图鉴
+Copyright © 2026 世界航海
+Licensed under the MIT License (see LICENSE).
+
+Reused from the upstream project, with modifications:
+
+  - src/atlas/**      renderer components, atlas data (zh/en), lessons, quizzes,
+                      i18n dictionaries, stylesheet, 3D builders, CIF-driven
+                      custom structures
+  - src/electron/**   CIF lexer/parser/space-group expansion/structure extraction,
+                      settings and notes schema
+
+Modifications: the stylesheet is scoped to `.sw-atlas`; the 3D stage is driven by
+plain three.js instead of @react-three/fiber, @react-three/drei and n8ao; the
+Vite-only builder registry is replaced by a generated static map; the Electron
+preload bridge is replaced by a page-side implementation; drag-and-drop and
+keyboard handling are scoped to the panel; a CIF file picker and a download-based
+notes export replace the native menu and save dialog.
+
+Original to this package
+------------------------
+
+  - index.js, client.js (build output), cordis.patch.yml, package.json
+  - src/client/**     slot registration, theme and locale inheritance, the page
+                      bridge, the panel shell styles
+  - scripts/build.mjs build pipeline
+  - icon.svg          original artwork

package/README.md

@@ -1,3 +1,158 @@
-# Temporary Holding Version
+# solids-world for DeepSeek Harness
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An interactive 3D atlas of solid-state and atomic physics, delivered as a DeepSeek
+Harness plugin: **固体世界 / Solids world**.
+
+This package re-hosts the desktop app
+[solids-world](https://github.com/nashihang777/solids-world) inside the Harness
+Web page. It contributes a global sidebar icon and a full central panel, so the
+atlas reads like a first-class part of the app rather than a widget.
+
+## What it does
+
+- **53 bilingual atlas entries** in five sections: crystal structures (12),
+  Bravais lattices (14), atoms and orbitals (11), symmetry (11), lattice
+  dynamics (5).
+- **Programmatic 3D**: every model is computed from the physics at run time —
+  spheres, bonds, cell frames, isosurfaces and animations. No model files, no
+  network access.
+- **Stepped lessons** whose camera focus and hotspot highlights follow each step,
+  plus a **quiz** per entry; passing both is recorded in the entry's progress.
+- **Notes** per entry, an aggregate view, and one-click **Markdown export**
+  (downloads a `.md` file).
+- **Gallery** of all entries with lesson/quiz status.
+- **Search** over Chinese, English, aliases and pinyin (`/` focuses the box).
+- **3D controls**: 1×/2× supercell, bonds, atom labels, clipping planes, spin,
+  reset/focus/zoom; orbitals add isosurface threshold, phase mode, opacity,
+  nodal surfaces and radial range; symmetry and dynamics entries add play,
+  pause, speed, single-step and parameter sliders.
+- **CIF import**: drop a `.cif` file onto the panel or use **Open CIF** in the
+  top bar. Lexing, parsing, space-group expansion and structure extraction all
+  run locally; syntax errors, unknown space groups and oversized files are
+  reported.
+- **Bilingual** UI with a zh/en switch, a light/dark theme, and respect for the
+  system "reduce motion" preference.
+- **Keyboard**: arrow keys step entries, `/` focuses search, `F` focuses the
+  stage, `Ctrl/⌘+D` opens a random entry, `Esc` closes the topmost layer.
+
+## Install
+
+From the workspace that contains this directory:
+
+1. Make sure `client.js` is present (it is committed). To rebuild it, see below.
+2. Install the bundle from the parent directory with the plugin manager,
+   pointing at this package directory:
+
+   ```
+   plugin_manager action=install_bundle target=<absolute path to solids-world-harness>
+   ```
+
+3. Open **固体世界 / Solids world** from the sidebar panel column. Its icon sits
+   below the built-in panel icons.
+
+The bundle stores settings and notes in the page's `localStorage`, so they
+survive a restart, and stay independent of any other profile data.
+
+## Build
+
+`client.js` is generated. Rebuild after changing anything under `src/`:
+
+```bash
+node scripts/build.mjs
+```
+
+The build needs esbuild, postcss and `three`. It looks for them in
+`node_modules/` here first, then in a `solids-world` checkout (default: the
+sibling `../solids-world`, or wherever `SOLIDS_WORLD_SRC` points). So either
+`npm install` in this folder, or clone the
+[upstream app](https://github.com/nashihang777/solids-world) and point
+`SOLIDS_WORLD_SRC` at it. Running the plugin never needs either: `client.js` is
+standalone.
+
+`tsconfig.json` is for editors and type checking only. The build pins its own
+compiler options (`tsconfigRaw`), so it cannot drift with that file — notably it
+keeps `useDefineForClassFields: false`, the semantics the upstream Vite build
+used.
+
+The script:
+
+1. generates `src/atlas/three/builders-map.ts` — the desktop app enumerated its
+   53 builders with Vite's `import.meta.glob`, which esbuild does not support;
+2. scopes the desktop stylesheet to `.sw-atlas` with PostCSS, so the atlas
+   cannot restyle the host page;
+3. bundles `src/client/index.tsx` as an IIFE with three.js inlined and `react`
+   resolved to the host's instance;
+4. wraps the bundle in the `window.__ModuleLoader__.load` factory contract.
+
+## Verify
+
+Two headless checks ship with the sources. Both reuse the `solids-world`
+checkout's `node_modules`, so no install is needed:
+
+```bash
+node scripts/smoke.mjs          # loads client.js like the module loader does
+node scripts/check-content.mjs  # atlas data, 53 models, CIF samples
+```
+
+`smoke.mjs` runs the built bundle inside jsdom with a stand-in module loader and
+host context, mounts the panel and asserts what a broken port would lose: the
+scoped panel root, inherited theme and locale, all 53 library rows, entry
+selection, the help modal, the CIF input, settings/notes persistence, language
+switching, and cleanup on unload. jsdom has no WebGL, so the 3D stage degrades
+to its fallback notice there.
+
+`check-content.mjs` asserts that both locales expose the same 53 entries with
+lessons and quizzes, that every entry owns exactly one 3D builder, that all 53
+models construct in 1× and 2× supercells, that a parsed CIF becomes a model, and
+that the bundled CIF samples still produce their recorded atoms, elements and
+error codes.
+
+Type checking uses the same checkout:
+
+```bash
+New-Item -ItemType Junction -Path node_modules -Target ../solids-world/node_modules
+node node_modules/typescript/bin/tsc -p tsconfig.json --noEmit
+```
+
+A page refresh (or a Harness restart) is needed after rebuilding `client.js` to
+load the new Client module generation.
+
+## Layout
+
+```
+index.js                 Host half (the atlas needs no Host service)
+client.js                built Client half
+cordis.patch.yml         bundle row
+locale/{en,zh}.json      display metadata
+src/client/index.tsx     slot registration, theme/locale inheritance, icon
+src/client/bridge.ts     page replacement for the Electron preload
+src/atlas/**             the desktop renderer, ported
+src/electron/**          CIF parser + settings/notes schema, ported
+```
+
+The two regressions worth knowing about when editing `src/atlas`: `three/Stage.tsx`
+is rewritten against plain three.js (the host page supplies no react-three-fiber),
+and `App.tsx` scopes drag-and-drop plus keyboard handling to the panel instead of
+the whole document.
+
+## Differences from the desktop app
+
+- **No post-processing**: the N8AO ambient-occlusion and bloom passes are gone,
+  because they need react-three-fiber's composer. The `postfx` setting now only
+  selects the render resolution tier. Lighting, geometry, materials and colors
+  are otherwise unchanged.
+- **No native window chrome**: regressions live in the panel; the Electron menu
+  becomes the top bar's **Open CIF** button, and the notes export downloads a
+  file instead of opening a save dialog.
+- **Keyboard shortcuts are panel-scoped** so they never steal keys from the
+  Harness shell.
+- **Layout breakpoints** are viewport-based in the original stylesheet; in a
+  narrow panel on a wide screen the three-column layout keeps its desktop
+  proportions.
+
+## Attribution and license
+
+MIT. The renderer, entry data, lessons, quizzes and CIF parser come from
+**solids-world** (© 2026 世界航海, MIT) — see [NOTICE](./NOTICE) and
+[LICENSE](./LICENSE). The plugin scaffolding (bundle manifest, client entry,
+page bridge, build script, icon) is original to this package.