@ihyeon/flow-qa 0.0.0-stage → 0.1.0-alpha.2

package/dist/src/workspace.js

@@ -0,0 +1,88 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { resolve, dirname } from 'node:path';
+import { createHash } from 'node:crypto';
+import { configSchema, suiteSchema } from "./schema.js";
+export const CONFIG_FILE = 'flowqa.config.json';
+export async function readConfig(workspace) {
+    try {
+        return configSchema.parse(JSON.parse(await readFile(resolve(workspace, CONFIG_FILE), 'utf8')));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            throw new Error('flowqa.config.json is missing. Run flow-qa init first.');
+        throw error;
+    }
+}
+export async function readSuite(path) {
+    return suiteSchema.parse(JSON.parse(await readFile(path, 'utf8')));
+}
+export async function writeJSON(path, data, exclusive = false) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(data, null, 2)}\n`, { flag: exclusive ? 'wx' : 'w', mode: 0o600 });
+}
+export function sha256(text) { return createHash('sha256').update(text).digest('hex'); }
+export async function verifySuiteSource(suite, workspace) {
+    if (!suite.source)
+        return;
+    let source;
+    try {
+        source = await readFile(resolve(workspace, suite.source.file), 'utf8');
+    }
+    catch {
+        throw new Error('Cannot read the source flow for these cases. Restore the file or regenerate the cases from the specification.');
+    }
+    if (sha256(source) !== suite.source.sha256)
+        throw new Error('STALE_SUITE: The flow changed. Regenerate the cases from the current specification.');
+}
+export const demoFlow = `# Create and filter tasks\n\nThe target is the local demo app included with Flow QA. Each test starts with an empty list.\n\n## Confirmed requirements\n- Entering a title and adding it displays the title in the list.\n- Adding an empty title shows the error 'Enter a task title.'\n- A completed task disappears from the 'Active' filter and remains visible under 'All'.\n\n## UI contract\n- Title input: label 'Task title'\n- Add button: role button, name 'Add'\n- List: testId 'task-list'\n- Empty title error: role alert\n- Complete button: role button, name 'Complete'\n- Filters: role button, name 'Active' or 'All'\n\n## Execution scope\nOnly temporary items in the local demo are used. No external account, real payment, or persistent storage is involved.\n`;
+export const demoSuite = suiteSchema.parse({
+    schemaVersion: 'flow-qa/suite-1', id: 'task-flow', title: 'Create and filter tasks',
+    requirements: [
+        { id: 'R1', text: 'A task is added with the entered title.' },
+        { id: 'R2', text: 'Adding an empty title shows an error.' },
+        { id: 'R3', text: 'Completed tasks are hidden from Active and remain under All.' },
+    ],
+    cases: [
+        { id: 'TC-001', title: 'Create a task with a title', requirementIds: ['R1'], preconditions: ['Empty list on a new page'], questions: [], steps: [
+                { type: 'open', path: '/' }, { type: 'fill', locator: { by: 'label', value: 'Task title' }, value: 'First QA run' },
+                { type: 'click', locator: { by: 'role', value: 'button', name: 'Add' } },
+                { type: 'assertText', locator: { by: 'testId', value: 'task-list' }, expected: 'First QA run', match: 'contains' },
+            ] },
+        { id: 'TC-002', title: 'Show an error for an empty title', requirementIds: ['R2'], preconditions: ['Empty list on a new page'], questions: [], steps: [
+                { type: 'open', path: '/' }, { type: 'click', locator: { by: 'role', value: 'button', name: 'Add' } },
+                { type: 'assertText', locator: { by: 'role', value: 'alert' }, expected: 'Enter a task title.', match: 'equals' },
+            ] },
+        { id: 'TC-003', title: 'Hide completed tasks from Active', requirementIds: ['R3'], preconditions: ['Empty list on a new page'], questions: [], steps: [
+                { type: 'open', path: '/' }, { type: 'fill', locator: { by: 'label', value: 'Task title' }, value: 'Task to complete' },
+                { type: 'click', locator: { by: 'role', value: 'button', name: 'Add' } },
+                { type: 'click', locator: { by: 'role', value: 'button', name: 'Complete' } },
+                { type: 'click', locator: { by: 'role', value: 'button', name: 'Active' } },
+                { type: 'assertVisible', locator: { by: 'text', value: 'Task to complete' }, visible: false },
+                { type: 'click', locator: { by: 'role', value: 'button', name: 'All' } },
+                { type: 'assertVisible', locator: { by: 'text', value: 'Task to complete' }, visible: true },
+            ] },
+    ],
+});
+export async function initWorkspace(workspace) {
+    const written = [];
+    const files = {
+        [CONFIG_FILE]: `${JSON.stringify(configSchema.parse({ schemaVersion: 'flow-qa/config-1', targets: { demo: { url: 'http://127.0.0.1:4178', description: 'Local task demo' } } }), null, 2)}\n`,
+        'flows/task-flow.md': demoFlow,
+        'cases/task-flow.json': `${JSON.stringify({ ...demoSuite, source: { file: 'flows/task-flow.md', sha256: sha256(demoFlow) } }, null, 2)}\n`,
+        '.gitignore': '.flowqa/\n.env\n.env.*\n',
+        '.flowqa/.gitignore': '*\n',
+    };
+    for (const [file, content] of Object.entries(files)) {
+        const path = resolve(workspace, file);
+        await mkdir(dirname(path), { recursive: true });
+        try {
+            await writeFile(path, content, { flag: 'wx', mode: 0o600 });
+            written.push(file);
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+        }
+    }
+    return written;
+}

package/docs/architecture.md

@@ -0,0 +1,38 @@
+# Architecture and verification boundaries
+
+The local CLI and loopback web UI share one workspace format, case schema, execution path, and report contract. Flow QA runs browser tests against a target URL; it does not need the target application's source code.
+
+```mermaid
+flowchart LR
+  A[Flow document] --> B[Planning prompt or planner model]
+  B --> C[JSON case suite]
+  C --> D[Schema and source-hash validation]
+  D --> E[Compile allowed steps to e2e code]
+  E --> F[tester-army/e2e browser run]
+  F --> G[QA report with attempts and evidence]
+  H[CLI / local UI] --> B
+  H --> D
+  H --> F
+  I[Optional agent model] --> F
+```
+
+## Decisions at each boundary
+
+**Planning and execution are separate.** A `planner` designs cases from a flow; an `agent` is used only for `act` and `assertAgent` steps during execution. They are configured independently. Users review the generated JSON before running it, and fixed steps run without either model. Users choose model and target addresses; authentication values come from named environment variables rather than the config JSON.
+
+**Only a defined vocabulary compiles.** The schema checks requirement references, assertions, step types, and inputs. It does not execute arbitrary code or shell commands from model output. Cases with unresolved `questions`, or steps that need an unavailable agent model, are blocked. `preconditions` describe required state; they are not an automatic setup contract.
+
+**Source and evidence stay linked.** Planning records the source flow's SHA-256 hash in the suite. `validate`, `generate`, and `run` check it again and stop when the flow changed. Each execution writes a new directory with a suite snapshot, generated tests, raw engine output, and Markdown/JSON reports. Previous evidence is not reused as a current success. `compare` permits a direct comparison only for the same suite hash and target URL; it cannot establish that external data was unchanged.
+
+**Blocked and failed mean different things.** An unreachable app or unresolved question is blocked; an assertion mismatch is failed. A pass after retry has its own status. Engine output is validated rather than treating missing results as passes. The report records observations, not a root-cause verdict on the product.
+
+## Ownership
+
+| Area | Flow QA provides | External implementation or prerequisite |
+| --- | --- | --- |
+| Planning | Prompt, model connection, JSON schema validation | User-selected OpenAI-compatible model |
+| Execution | Step compilation, target connection, orchestration, cancellation | [tester-army/e2e](https://github.com/tester-army/e2e), Chromium |
+| Results | A fresh report per run, status interpretation, evidence links | Raw runs and evidence from the engine |
+| UI | Local workflow screens and English/Korean language switch | [Hyeonse Design System](https://github.com/hyeonse-swing/hyeonse-design-system) tokens and preference utilities |
+
+The UI binds only to `127.0.0.1` and serves approved report evidence, not arbitrary raw logs or HTML/SVG. Local reports may still contain data from the tested app and should be reviewed before sharing. This alpha does not manage login sessions, cap model spending, schedule CI runs, or support mobile devices.

package/docs/releases.md

@@ -0,0 +1,54 @@
+# Alpha release and verification
+
+## 0.1.0-alpha.2
+
+This update replaces the introductory video link with two UI screenshots. Runtime behavior is unchanged from alpha.1. Media files are not included in the npm tarball.
+
+This public alpha provides a local CLI and UI, structured case validation, browser-run orchestration, and QA reports linked to evidence. Its bundled to-do app demo runs without a model.
+
+- Package: [`@ihyeon/flow-qa@0.1.0-alpha.2`](https://www.npmjs.com/package/@ihyeon/flow-qa/v/0.1.0-alpha.2), with the `alpha` dist-tag
+- Source and package: [GitHub alpha release](https://github.com/hyeonse-swing/flow-qa/releases/tag/v0.1.0-alpha.2)
+- Public checks: [GitHub Actions](https://github.com/hyeonse-swing/flow-qa/actions/workflows/ci.yml)
+
+### Local evidence
+
+Checked on macOS with Node.js 24.14.1 on 2026-10-08. The English-default and Korean UI share the same execution and data contracts.
+
+| Check | Observed result |
+| --- | --- |
+| Types, unit tests, UI static checks | 45 tests, type checking, JavaScript syntax, and the design-system token audit passed |
+| Real Chromium | Three normal cases passed; an intentional assertion failure and an unreachable app were classified separately |
+| Package contents | Compiled CLI, UI, demo, and bundled design system included; workspace data, run results, and secret files excluded |
+| Tarball in a fresh consumer workspace | Installed with Git execution disabled; CLI, UI, fonts, and the three actual cases passed |
+| Language behavior in Chromium | English first visit, Korean switching, persisted preference, cross-tab sync, preserved edits and review, live run completion, localized Markdown downloads, and 390px viewport passed |
+| Runtime dependency audit | `npm audit --omit=dev` found no known vulnerabilities at the time of the check |
+
+These browser checks used a locally installed Chromium. They do not prove first install on a clean OS, authenticated behavior in another service, or real-model quality and cost. Dependency audit results are time-sensitive.
+
+### Reproduce
+
+```sh
+npm ci
+npm run check
+npm run qa -- browser install
+npm run demo:smoke
+npm run smoke:ui
+npm run check:package
+npm run smoke:package
+```
+
+`check:package` checks the distribution file list and required resources. `smoke:package` installs the tarball into a temporary consumer workspace, then checks the CLI, UI, and real browser run. It writes results to `output/package/tarball-smoke.json`, outside the published package.
+
+Check the published registry version separately. The script requires the installed package name and version to match the current `package.json` exactly.
+
+```sh
+FLOWQA_PACKAGE_SPEC=@ihyeon/flow-qa@0.1.0-alpha.2 npm run smoke:package
+```
+
+Registry results are written to `output/package/registry-smoke.json`. GitHub CI checks types and tests, Chromium pass/fail/blocked cases, and tarball installation on Linux; its artifacts contain the check results. Confirm publication and CI independently on the package page and the workflow run for the relevant commit.
+
+### Scope and credits
+
+This alpha does not provide login-session setup, a model-spending cap, scheduled CI runs, or a shared team server. Case planning and natural-language browser action use separately configured OpenAI-compatible APIs; local demo checks do not establish model quality or behavior in an external authenticated app. The UI library lists only top-level `cases/*.json` and linked `flows/*.md` files.
+
+The browser engine is `e2e@0.16.0` with `@e2e-dev/web@0.11.1`. The design system is fetched from a pinned public HTTPS source and bundled with the npm package, so consumers do not need GitHub authentication to install it. See the [third-party notices](../THIRD_PARTY_NOTICES.md) for component licenses.

package/docs/ui.md

@@ -0,0 +1,71 @@
+# Flow QA local UI
+
+Use the target app's URL and a user flow to review cases, run them, and inspect results. The local example is a to-do app; the UI does not bundle an organization's product list, internal URLs, accounts, model catalog, work cases, or run history.
+
+## Start
+
+Node.js 24 or later is required. Install the alpha and start the local demo:
+
+```sh
+npm install -g @ihyeon/flow-qa@0.1.0-alpha.2
+flow-qa browser install
+flow-qa ui --demo
+```
+
+The default UI address is `http://127.0.0.1:4310`. The command prints the demo app address. Use `flow-qa ui --demo --port 4311` for another port. Ctrl+C stops the active run and the servers started by this command.
+
+To open an existing workspace:
+
+```sh
+flow-qa ui
+# or specify another Flow QA workspace
+flow-qa ui --workspace ./my-qa --port 4311
+```
+
+Create a workspace first with `flow-qa init ./my-qa`. From source, use `npm ci`, `npx playwright install chromium`, and `npm run ui:demo`. The server binds only to `127.0.0.1`; it is not a hosted team service.
+
+The UI starts in **English**, regardless of browser language. Switch to **한국어** from the top bar. The selection is saved under `flowqa-language` in this browser and applies on the next visit. It changes product copy and the labels in Markdown reports downloaded from the UI; it does not translate user-written flows, target descriptions, case titles, target apps, or model responses. Saved `qa-report.json` and `qa-report.md` use English product wording and unchanged status codes. CLI messages default to English; `--lang en|ko` takes precedence over `FLOW_QA_LANG`.
+
+## Workflow
+
+1. **Connections:** Register a target name and URL. Planner and browser agent models have separate settings.
+2. **Scenario:** Describe the initial state, actions, screen elements, and expected results. If a planner is ready, ask it to create cases. Without a model, download the planning prompt and paste a JSON response from an AI you already use.
+3. **Review and save cases:** Expand each case to read preconditions, actions, expected results, and unresolved questions. Editing the JSON keeps the linked flow; if that source flow changes, design the cases again. Planning and running are separate actions. Editing inputs or connection settings alone does not call a model.
+4. **Run QA:** Review the saved case file, select a target, and check the review confirmation before running. If the file changes after review, reload and review it again. Fixed steps need no agent model. `act` and `assertAgent` require a compatible agent; missing models and unresolved questions are reported as blocked cases.
+5. **Case library and Run history:** Save cases as new files and load them again. Open run details to see each case, attempt, and evidence; download the Markdown or JSON report.
+
+The top bar shows planning, running, and stopping states, plus a cancel button. A late planning response cannot change the draft after cancellation. The UI does not estimate progress inside an individual browser action. If the server disconnects, reconnect; runs started in another tab also appear. Refreshing settings rereads targets and models, so save edits first.
+
+For each attempt, the report can open or download an approved screenshot or text evidence item. It serves only evidence linked to the report and marked as redacted or not needing redaction. It does not serve arbitrary files, raw run logs, HTML, or SVG. Markdown and JSON downloads summarize results but do not include evidence files. Keep the original run directory structure if you need relative evidence links in an offline Markdown report.
+
+**Connections** shows whether Chromium is installed. A model key marked ready means only that the named environment variable exists; it does not prove authentication or model compatibility. Case review shows runnable and pre-blocked counts. Login and target reachability are established only by an actual run.
+
+To enter fresh JSON after changing a scenario, open the JSON editor in case review and choose **New JSON draft**. Existing saved files remain; validate and save the new JSON before reviewing it for a run.
+
+## Display and language
+
+The UI uses role tokens and preference utilities from `@hyeonse/design-system`, pinned to GitHub commit `38978c6a86f422fc0e63e919f600bc2dd3451e5c`. Flow QA implements its own workflow layout, buttons, and fields with those tokens.
+
+The top-bar theme button and **Connections → Display settings** control theme, accent, density, corners, and motion. Preferences are saved under `flowqa-display-preferences` in the browser and shared across tabs. The device's reduced-motion setting takes priority. The saved preferences are applied before the token CSS appears on first load.
+
+Local DM Sans and a Noto Sans KR subset are used for typography; missing Korean glyphs fall back to installed system fonts. See the [font and package notices](../THIRD_PARTY_NOTICES.md).
+
+## Model connections
+
+In the UI, configure an OpenAI-compatible Chat Completions base URL, model ID, and the **name** of an environment variable containing an API key. A local model can be used if it supports the same contract; confirm its API, tool, and image capabilities separately.
+
+There is no field for the token value. Supply keys to the environment that starts the UI server. Flow QA does not read `.env` files automatically and does not save keys in browser storage. Changing a variable name does not create its value.
+
+Without a model, you can still download prompts, review existing cases, and run fixed steps. If a generated response does not satisfy the suite schema, the UI identifies fields to fix (for example, `cases.0.steps` means the first case's steps). Clarify missing expectations in the scenario and regenerate, or edit JSON from a downloaded prompt. There is no automatic retry. Canceling a request stops this app from accepting its result; it does not guarantee that the provider stops processing or charging.
+
+The report displays token use and estimated cost only when supplied by the execution engine. Case-planning cost is separate; there is no total cost aggregation or spending cap.
+
+## Storage and limits
+
+- A normal UI workspace uses `flowqa.config.json`, `flows/`, `cases/`, and `.flowqa/runs/` in the selected directory.
+- Demo mode writes to `.flowqa/ui-demo-en/`, keeping earlier Korean demo data separate. On restart it reconnects the demo app to its new local URL and resets model settings; saved cases and run history remain. Switching the UI language does not translate either demo data or user-authored text.
+- The UI library lists only top-level `cases/*.json` and their linked `flows/*.md`. Use the CLI to validate and run cases in nested directories.
+- Saving creates a new case file. The UI does not overwrite or delete an existing one.
+- Run history may contain data from the tested app. Inspect reports and evidence before downloading or sharing them.
+- A failed assertion is an observed result, not proof of a product defect. Unverified cases are never shown as passed.
+- This UI has no login-session capture, automatic regression recording, batch execution, CI scheduler, or team permissions. It uses the same run and report contract as the CLI.

package/licenses/DM-Sans-LICENSE.txt

@@ -0,0 +1,93 @@
+Copyright 2014 The DM Sans Project Authors (https://github.com/googlefonts/dm-fonts) DMSans-Italic[opsz,wght].ttf: Copyright 2014 The DM Sans Project Authors (https://github.com/googlefonts/dm-fonts)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/licenses/Noto-Sans-KR-LICENSE.txt

@@ -0,0 +1,93 @@
+Google Inc.
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/node_modules/@hyeonse/design-system/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: Design system
+on:
+  push:
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run check
+      - run: npm run build
+      - run: npm test
+      - run: git diff --exit-code -- dist
+      - run: npm pack --dry-run

package/node_modules/@hyeonse/design-system/.npmignore

@@ -0,0 +1,5 @@
+node_modules
+.DS_Store
+*.log
+*.tgz
+output/

package/node_modules/@hyeonse/design-system/AGENTS.md

@@ -0,0 +1,10 @@
+# Hyeonse Design System 작업 지침
+
+이 저장소는 개인 프로젝트용 디자인 시스템입니다. 기존 화면의 목적과 실제 사용 맥락을 먼저 확인하고, 역할 토큰과 검증 가능한 상태를 기준으로 작업합니다.
+
+- 공개 계약은 `package.json`의 exports, `src/`, `docs/api.md`를 함께 확인합니다. 문서만 보고 존재하지 않는 컴포넌트를 가정하지 않습니다.
+- 기존 포트폴리오의 디자인 원칙은 `docs/foundations.md`에 요약되어 있습니다. 원본 구현이 필요할 때만 `https://github.com/hyeonse-swing/hyeonse-portfolio/blob/main/DESIGN_SYSTEM.md`를 참고합니다.
+- 새 화면이나 이관은 사용자 범위와 기존 동작을 보존합니다. 토큰 매핑은 색 값의 근접성보다 의미와 대비를 먼저 봅니다.
+- 상태 변경은 키보드, 좁은 화면, 밝음·어두움, 기기 움직임 감소 설정에서 확인합니다. 확인하지 않은 상태를 통과했다고 기록하지 않습니다.
+- 외부 사이트 게시, 커밋·푸시·PR 생성은 별도 요청 없이 진행하지 않습니다.
+- `skills/hyeonse-design-system/SKILL.md`는 이 저장소와 함께 제공하는 개인용 작업 지침입니다. 설치하거나 전역 설정을 바꾸지 않습니다.

package/node_modules/@hyeonse/design-system/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hyeonse Im
+
+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/node_modules/@hyeonse/design-system/README.md

@@ -0,0 +1,67 @@
+# Hyeonse Design System
+
+개인 프로젝트에서 같은 시각 언어와 화면 설정을 재사용하기 위한 작은 디자인 시스템입니다. 흰 바탕, 짙은 글자, 코발트 강조색을 기본으로 하며 포레스트·코랄 강조색과 다크 화면을 지원합니다. 출발점은 [포트폴리오의 실제 구현](https://github.com/hyeonse-swing/hyeonse-portfolio/blob/main/DESIGN_SYSTEM.md)입니다.
+
+## 사용
+
+Node.js 22 이상과 npm을 사용합니다. npm 레지스트리에 게시하지 않고 GitHub 버전에서 설치합니다.
+
+```sh
+npm install github:hyeonse-swing/hyeonse-design-system#v0.1.0
+```
+
+배포하는 앱에서는 검증한 전체 커밋 SHA로 고정하는 것을 권장합니다. 빌드된 `dist/`가 저장소에 포함되어 설치 시 별도 빌드는 필요하지 않습니다. 저장소를 개발하거나 견본을 확인할 때는 다음을 실행합니다.
+
+```sh
+cd hyeonse-design-system
+npm ci
+npm run build
+npm run check
+npm test
+python3 -m http.server 8000
+```
+
+브라우저에서 `http://localhost:8000/`을 열면 [쇼케이스](index.html)를 볼 수 있습니다. 빌드된 `dist/`를 참조하므로 먼저 `npm run build`를 실행해야 합니다.
+
+개인용 스킬은 소비 프로젝트에서 다음 명령으로 추가할 수 있습니다.
+
+```sh
+npx skills add hyeonse-swing/hyeonse-design-system --skill hyeonse-design-system
+```
+
+CSS만 필요한 화면에는 두 파일을 순서대로 불러옵니다.
+
+```css
+@import '@hyeonse/design-system/tokens.css';
+@import '@hyeonse/design-system/components.css';
+```
+
+React 화면에서는 `@hyeonse/design-system/react`의 `PreferencesProvider`, `ThemeToggle`, `PreferencesPanel`, `usePreferences`를 사용합니다. 초기 테마 깜빡임을 줄이려면 `@hyeonse/design-system/preferences`의 `preferenceScript`를 문서 `<head>`에 CSS보다 먼저 삽입하세요. 다른 저장 키가 필요하면 `createPreferenceScript(storageKey)`를 사용하고 Provider에도 같은 `storageKey`를 전달합니다. 기본 저장 키는 `hyeonse-site-preferences`입니다.
+
+```tsx
+import { PreferencesProvider, ThemeToggle, PreferencesPanel } from '@hyeonse/design-system/react';
+import { preferenceScript } from '@hyeonse/design-system/preferences';
+import '@hyeonse/design-system/tokens.css';
+import '@hyeonse/design-system/components.css';
+
+// 서버 문서의 <head> 안에서 CSS보다 먼저: <script dangerouslySetInnerHTML={{ __html: preferenceScript }} />
+export function DisplaySettings() {
+  return <PreferencesProvider><ThemeToggle locale="ko" /><PreferencesPanel locale="ko" /></PreferencesProvider>;
+}
+```
+
+설정 키나 이벤트 이름을 바꾸는 경우에는 [API 문서](docs/api.md)의 적용 범위를 확인하세요. 글꼴 파일은 [출처와 라이선스](THIRD_PARTY_NOTICES.md)를 확인한 뒤 제품 자산으로 따로 제공해야 합니다.
+
+## 구성
+
+- [기초 규칙](docs/foundations.md): 색의 역할, 글자, 밀도, 모서리, 움직임.
+- [API와 통합](docs/api.md): CSS 선택자와 TypeScript·React 공개 API.
+- [개인용 스킬](skills/hyeonse-design-system/SKILL.md): 새 화면 제작, 확장, 토큰 매핑, 이관, 리뷰와 문서화의 작업 기준.
+
+`src/`가 배포 코드의 기준이며 쇼케이스는 그 출력을 검토하는 정적 문서입니다. 쇼케이스의 예시 마크업은 CSS 상태 견본입니다. 라이브러리에서 일반 Button·Input React 컴포넌트를 제공한다는 의미는 아닙니다.
+
+[실제 통합 검증 기록](docs/verification.md)에는 포트폴리오 이관 전후 비교와 확인 범위를 남겼습니다.
+
+## 소비 앱의 CSS 점검
+
+패키지 빌드 후 소비 앱 루트에서 `hds-audit <consumer-root> [config-relative-path]`를 실행할 수 있습니다. 기본 설정 파일은 소비 앱 루트의 `design-system.audit.json`입니다. [설정 형식과 한계](docs/audit.md)를 확인하세요. 이 검사는 CSS의 원시 색상 사용과 공유 토큰 재정의를 점검하며, TypeScript·JavaScript·3D 머티리얼까지 검사했다는 뜻은 아닙니다.

package/node_modules/@hyeonse/design-system/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,5 @@
+# 제3자 자료
+
+이 저장소의 시각 규칙과 구현은 [개인 포트폴리오 디자인 시스템](https://github.com/hyeonse-swing/hyeonse-portfolio/blob/main/DESIGN_SYSTEM.md)을 기반으로 합니다. 작업 흐름의 참고 자료는 [Arlan Marat의 `arla6ka/skills`](https://github.com/arla6ka/skills/tree/e6ca7a5ff640c133ad1290b1271a23324f255155/skills)입니다. 참조한 정확한 리비전은 `e6ca7a5ff640c133ad1290b1271a23324f255155`입니다. 원본은 MIT License이며 저작권 고지 전문은 [licenses/arla6ka-MIT.txt](licenses/arla6ka-MIT.txt)에 보존했습니다. 이 저장소에는 원본의 여러 스킬을 복제하지 않고 개인 작업에 맞춘 하나의 스킬을 작성했습니다.
+
+쇼케이스의 DM Sans와 Noto Sans KR 글꼴 파일은 기존 포트폴리오 자산에서 복사했습니다. 각 라이선스 전문은 [DM Sans](licenses/DM-Sans-LICENSE.txt), [Noto Sans KR](licenses/Noto-Sans-KR-LICENSE.txt)에 있습니다. 한국어 서브셋은 기존 포트폴리오의 공개 문구용이므로 새 화면의 전체 한국어 문자 지원을 보장하지 않습니다.